随笔十：文档

大多数工程师维护、使用文档时共同的一个抱怨就是文档质量的问题。

软件工程师总是需要自己编写文档。

 

什么是文档

　　工程师为了完成工作而需要编写的所有补充文档，不仅是独立文档、还有代码注释。

 

为什么需要文档

　　高质量的文档对工程组织帮助很大。

　　代码和API变得更容易理解，可以减少犯错。

　　当设计目标与团队目标在文档中清晰的描述，项目团队就可以更好的聚焦工作。

　　如果步骤清晰，工程师更容易遵循步骤来手工操作流程。

　　如果流程由清晰的文档记录，那么当新成员加入时或者代码库时会更省事。

 

　　文档需要更多的前期投入，而且很就以后才能为作者带来明显的收益。

　　为什么工程师认为编写文档是一件糟糕的事情？

　　　　工程师常常把写作堪称一门独立的技能，而不是编程的技能。

　　　　有些工程师觉得自己不是一个能干的作家

　　　　没有工具或者没有集成到开发人员工作流中，编写文档往往变得更加困难。

　　　　文档被看作为额外的负担，而不是使代码的维护变得更加容易的东西。

　　文档的受益者往往是多个团队。

　　　　帮助指定API。编写文档是弄清楚API是否有意义的最可靠的方法之一。

　　　　提供维护路线图和历史记录。

　　　　使你的代码看起来更专业，并且吸引更多关注。

　　　　将减少其他用户提出的问题。

 

像代码一样对待文档

　　文档没什么不同，它也是一种工具，与代码一样，文档也有所有者。

　　你的文档应该做到如下几点：

　　　　有要遵循的内部政策或者规则

　　　　置于源代码管理系统之下

　　　　有明确的责任主体负责维护

　　　　进行变更评审

　　　　跟踪问题，就像在代码中跟踪缺陷一样

　　　　定期评估

　　　　如果可能的话，要对准确性、有效性等方面进行度量。

　　工程师越把文档看成是软件开发的必要任务之一，那么他们就不会抱怨写作带来的前期投入和成本，好的文档可以让他们获得更多的长期收益。

 

了解文档的作者

　　不用为自己编写文档，这是工程师常犯的错误。

　　在开始写作之前就要明确目标读者。

　　好的文档无需修饰或者“完美”，不要过度的设计文档。

　　

　　读者类型

　　　　基于一个或者多个标准：

　　　　　　经验水平

　　　　　　领域知识

　　　　　　目的

　　　　诀窍是以一种尽可能广泛的适用于不同受众群体的方式来写作。

　　　　写文档需要平衡，做适当的平衡有助于保持文档的简短。

　　　　另一个区分读者的维度是基于用户解除的文档方式：

　　　　　　有目的的搜索者往往知道自己想要什么，也知道自己正在寻找的东西是否符合要求。

　　　　　　困惑者，他们可能并不知道他们到底想要什么

　　　　最后，一个重要的区分读者的维度是客户和供应商。

 

文档类型

　　设计文档、代码注释、操作文档说明、项目页面等，。

　　了解不同文档类型很重要，而且不要混淆了这些类型。

　　有如下几类文档类型：

　　　　参考文档，包括代码注释

　　　　设计文档

　　　　新手教程

　　　　概念文档

　　　　着陆页面

　　参考文档

　　　　工程师最喜欢编写的文档，参考文档用于记录代码库内代码使用情况。　　

　　　　代码注释也是一种参考文档。

　　　　要保持代码注释的一致性。

　　文件注释

　　　　应该以正在阅读的代码中包含的内容的概要开始。

　　类注释

　　　　对于定义代码库中使用的API对象非常重要。

　　函数注释

　　　　函数做什么、返回什么的陈述性动词开始

　设计文档

　　　　设计文档的开发是工程师在部署新系统之前首要进行的工作之一，因此他也是确保能够覆盖各种关注点的比较合适的地方。

　　　　　一个好的设计文档应该包括设计目标、实现策略、并提出关键的设计决策。

　　　　　最好的设计文档会给出建议的设计目标并包括设计替代方案以及优缺点。

　　新手教程

　　　　帮助新同事尽快跟上节奏。

　　　　通常编写新手文档的最佳时间是第一次加入团队的时候。

　　　　大多数教程都要求你按照顺序执行许多步骤。

　　概念文档

　　　　有些代码需要比阅读参考文档更深入的解释和理解。

　　　　概念文档的一些示例可能是一个流行的API的库概念，等等。

　　　　概念文档没必要覆盖所有边缘案例。

　　　　概念文档最难的是编写的文档格式。

　　　　即使API的范围确定的很恰当，通常也应该提供一个独立的概念文档。

　　　　一份概念文档应该适用于广大的读者。

　　着陆页面

　　　　团队在公司内部的一个“团队页面”。

　　　　包括几个标题“首先阅读这里”等等

 

文档审核

　　所有的代码都要审核，文档也是一样。

　　技术文档有三种不同的评审类型：

　　　　技术评审，保证文档的准确性

　　　　读者评审，保证文档的清晰度

　　　　写作评审，保证文档的一致性

 

文档哲学

　　　WHO  WHAT WHEN WHERE与WHY

　　谁之前讨论过，其实就是文档的受众

　　what即文档的写作目的

　　when即文档是何时创建、评审、更新的

　　where信息通常暗含在文档中，决定文档应该位于何处

　　why即设置该文档的原因

 

　　开头、中间与结尾

　　优秀文档的要素

　　　　三个方面来判断：完整性、准确性、清晰度

　　　　如何提升文档质量？聚焦文档读者的需求。

　　丢弃文档

　　　　老代码会导致问题，老文档也会。

　　　　尽可能避免丢弃文档，但是文档不再起作用时，要将其删除。