技术团队如何维护文档

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

阅读余下内容

发表评论

电子邮件地址不会被公开。 必填项已用*标注


京ICP备12002735号