技术团队如何维护文档
source link: http://mp.weixin.qq.com/s/YQ6iyOnX59xUKOWQsOMFOw
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
技术团队如何维护文档
今天和大家说一个技术团队的老问题：一个长期持续迭代的项目，代码已经翻过很多次了，但是技术文档还是最初的样子，后来的技术人员依靠文档已经无法正确了解项目最初的样子了。或者是，技术文档写了很多，但是根本没人看，不同人写的文档不够统一和规范。
在讨论解决方案之前，我们首先将技术文档做一个分类：
1. 对外展示的技术文档，比如Tutorial、Programming Guide。
2. 从代码注释中由软件生成的，一般是API Guide文档。
3. 内部开发资料、参考资料，比如系统设计方案，技术设计方案。
由于第1类文档面对外部客户，受重视程度自然就高，所以不太存在无法同步更新的问题。
所以，我们今天的讨论，主要针对于第3类文档。
在我们日常的工作中，我们做了以下两件事：
1. 通过流程工具将技术文档绑定在团队的开发活动中。 对于一个模块级的改动，项目管理流程会要求更新文档。对于一些重要项目，要求有文档评审的会议。最后，文档的检查放在项目发布的 check-list 中。
2. 我们主张用用轻量的wiki 来维护，提供对应的文档模板。一方面不要求工程师提供精美格式的文档，同时让写文档尽可能的标准化，降低工程师的心里负担。
从理论上说，我们是希望能让代码和文档做到绝对映射，因为这保证了代码的改动都能被完整的记录下来。不过，作为互联网技术从业者，不可避免的都要面对代码改动的高频发生，投入的时间成本、不同工程师的文本语言统一，都会挑战文档和代码的匹配程度。
所以，我换了一种思路，思考我们团队到底需要一些什么技术文档。对每位工程师而言，提高代码本身的可读性，让代码结构更容易理解，比编写一份大而全的文档更有价值的事情。换个角度看，作为一名合格的工程师，要掌握前人工作，必须要仔细阅读代码而不是依赖文档来了解系统的细节。
所以，除了我以上提到的2点，我将团队的技术文档进行了必要的“瘦身”，我们团队只关注以下三类技术文档：
重要项目技术架构和解决方案（必备的两个文档：模块的详细设计 和 开发设计）
复杂的算法和数据结构
思维导图 （记录了会议中的不同角度观点）
至于我们在每个迭代发生了什么，依靠JIRA来详细记录，包括对Git提交的commit的统一格式要求。
降低了工程师的负担，同时，如果大家要看过去的文档，内容也非常的有针对性。
所以，文档写出来，不是为了完成任务，而是凝聚团队智慧的瞬间。
扫描二维码或手动搜索微信公众号【架构栈】： ForestNotes
欢迎转载，带上以下二维码即可
点击“阅读原文”，所有【架构栈】近期的架构文章汇总
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK