技术团队如何维护文档

流觞

今天和大家说一个技术团队的老问题：一个长期持续迭代的项目，代码已经翻过很多次了，但是技术文档还是最初的样子，后来的技术人员依靠文档已经无法正确了解项目最初的样子了。或者是，技术文档写了很多，但是根本没人看，不同人写的文档不够统一和规范。

在讨论解决方案之前，我们首先将技术文档做一个分类：

1. 对外展示的技术文档，比如Tutorial、Programming Guide。2. 从代码注释中由软件生成的，一般是API Guide文档。3. 内部开发资料、参考资料，比如系统设计方案，技术设计方案。

由于第1类文档面对外部客户，受重视程度自然就高，所以不太存在无法同步更新的问题。

所以，我们今天的讨论，主要针对于第3类文档。

在我们日常的工作中，我们做了以下两件事：

1. 通过流程工具将技术文档绑定在团队的开发活动中。 对于一个模块级的改动，项目管理流程会要求更新文档。对于一些重要项目，要求有文档评审的会议。最后，文档的检查放在项目发布的 check-list 中。

2. 我们主张用用轻量的wiki 来维护，提供对应的文档模板。一方面不要求工程师提供精美格式的文档，同时让写文档尽可能的标准化，降低工程师的心里负担。

从理论上说，我们是希望能让代码和文档做到绝对映射，因为这保证了代码的改动都能被完整的记录下来。不过，作为互联网技术从业者，不可避免的都要面对代码改动的高频发生，投入的时间成本、不同工程师的文本语言统一，都会挑战文档和代码的匹配程度。

所以，我换了一种思路，思考我们团队到底需要一些什么技术文档。对每位工程师而言，提高代码本身的可读性，让代码结构更容易理解，比编写一份大而全的文档更有价值的事情。换个角度看，作为一名合格的工程师，要掌握前人工作，必须要仔细阅读代码而不是依赖文档来了解系统的细节。

所以，除了我以上提到的2点，我将团队的技术文档进行了必要的“瘦身”，我们团队只关注以下三类技术文档：

• 重要项目技术架构和解决方案（必备的两个文档：模块的详细设计 和 开发设计）
• 复杂的算法和数据结构
• 思维导图 （记录了会议中的不同角度观点）
  

至于我们在每个迭代发生了什么，依靠JIRA来详细记录，包括对Git提交的commit的统一格式要求。

降低了工程师的负担，同时，如果大家要看过去的文档，内容也非常的有针对性。

所以，文档写出来，不是为了完成任务，而是凝聚团队智慧的瞬间。

无言者