工程师最讨厌写技术文档？

    高质量的文档对于一个组织或团队来说有非常多的益处，比如让代码和API更容易理解、错误更少；让团队成员更专注于目标；也可以让一些手工操作更容易；另外如果有新成员加入的话有文档也会让他们更快融入……    写文档有比较严重的收益滞后性，不像测试，你跑一个测试case，它能立即告诉你是对还是错，它的价值马上就体现出来了。而写一份文档，随着时间的推移，它的价值才会逐渐体现出来。你可能只写一次文档，将来它会被阅读上百次、上千次，因为一份好的文档可以在未来替你向别人回答类似下面这些问题。

• 为什么当时是这么决策的？
• 为什么代码是这样实现的？
• 这个项目里都有哪些概念？
  

    写文档同样对于写作者也有非常大的收益：

• 帮你构思规范化API： 写文档的过程也是你审视你API的过程，写文档时会让你思考你API设计是否合理，考虑是否周全。如果你没法用语言将API描述出来，那么说明你当前的API设计是不合理的。
• 文档也是代码的另一种展现： 比如你两年后回过头来看你写过的代码，如果有注释和文档，你可以很快速理解代码。
• 让你的代码看起来更专业： 我们都有个感觉，只要文档齐全的API都是设计良好的API，虽然这个感觉并不完全正确，但这两者确实是强相关的，所以在很多人眼里，文档的完善度也成为衡量一个产品专业度的指标。
• 避免被重复的问题打扰： 有些问题你只需要写在文档里，这样有人来问你的时候你就可以让他直接去看文档了，而不是又给他解释一遍。
  

    关于文档的重要性，每个技术人或多或少都知道一些，但很多人还是没有写文档的习惯，为什么？除了上文中提到的文档的收益滞后性外，还有以下几点原因：

• 很多工程师习惯将写代码和写作割裂开，不仅仅是在工作上，而且在思想上就认为它们是完全不相关的两项工作，这就导致好多人重代码不重文档。
• 也有很多工程师认为自己不善写作，索性就不写了。这实际是个偷懒的借口，写文档不需要华丽的辞藻、生动的语言，你只需要将问题讲清楚即可。
• 有时候工具不好用也会影响的文档写作。如果没有一个很好的写作工具将写文档嵌入到开发工作流程中的话，写作确实会增加工作的负担。
• 大多数人将写文档看做是工作的额外负担。我代码都没时间写，哪有时间写文档！，这其实是错误的观念，文档虽然前期有投入，但能让你代码的后期维护成本大幅降低，磨刀不误砍柴工这个道理相信大家都还是能理解的。
  

    既然理解了好文档的重要性，我们如何保证在时间的长河中维护好一份文档，这里有些相关的方**，大家可以参考下。

    对于如何写出好代码，整个技术圈已经有好多经验的总结了，比如书籍《重构》《代码简洁之道》…… 针对各种编程语言，也有相关的规范，比如国外的Google C++规范，国内的阿里Java开发规范等…… 相关推荐：万字 | 菊花厂C语言编程10大规范。但对于文档 似乎相关的资料却很少。但实际上，不应该把文档和代码割裂开来，你可以简单粗暴地认为文档其实就是用一种特殊语言书写的代码，这种语言就是人类的语言。这么想的话，实际上我们很多在代码和工程中总结出来的经验，也可以直接用在文档中，比如：

• 有统一的规范
• 有版本控制
• 有明确的责任人维护
• 有变更Review机制
• 有问题的反馈和更新机制
• 定期更新
• 有衡量的指标(比如准确性，时效性)
  

    写文档有一个很常见的错误，那就是很多人文档都是写给自己看的，这种情况下就会导致你的文档只有自己或者和你有相似知识背景的人才能看懂，团队较小时这种问题还好，你们都做着类似的工作，所以也都能看懂文档。但当团队逐渐壮大后，问题就会凸显出来，新人有时候有着和你不同的工作背景，甚至现在都做着不同的工作内容，这时候你之前写的文档他们就很难读懂了。    所以在写文档之前请明确你文档可能的读者会是哪些人，然后针对他们的特点着重关注如何才能让他们理解。当然，文档也不一定要非常严肃和完美，只要能向你潜在的读者说明问题即可。记住文档是写给别人看的，不是给自己看的。    根据专业水平可以大致将读者分为三种：新手、老手和专家，针对不同水平的人写作需要有侧重点。比如针对新手，你需要重点介绍下里面涉及到的术语和概念，然后详细讲解具体的的实现。相反，针对专家 你可以省去这些额外的信息。注意，这里没有严格的标准，因为有些文章新手会看，专家也会看， 这里还是需要具体情况具体分析。    另外一种对读者分类的方式就是根据读者阅读文档的目的来分类，比如有人知道自己遇到了什么问题，就是来找解决方案的。还有一批人只有一个简单的想法，但不知道具体的问题。举个例子，以读数据库慢为例，前者已经知道数据库慢可能是因为数据量巨大且没有加索引，解决方案很简单 加索引，这时候他可能需要知道的是如何正确地加索引。而后者可能着重关注的是为什么读数据库会慢，这时候你可能需要额外重点介绍下数据库相关的原理。