技术团队如何维护文档

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

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

1. 对外展示的技术文档，比如Tutorial、Programming Guide。

2. 从代码注释中由软件生成的，一般是API Guide文档。

3. 内部开发资料、参考资料，比如系统设计方案，技术设计方案。

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

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

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

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

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

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

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

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

重要项目技术架构和解决方案（必备的两个文档：模块的详细设计和开发设计）

复杂的算法和数据结构

思维导图（记录了会议中的不同角度观点）

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

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

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

扫描二维码或手动搜索微信公众号【架构栈】： ForestNotes

欢迎转载，带上以下二维码即可

点击“阅读原文”，所有【架构栈】近期的架构文章汇总

↓↓↓

技术团队如何维护文档相关推荐

oracle11gr2 active data guard,Oracle11gR2 Aactive DataGuard(手动)装配部署及维护文档（三）之升级及rman...
Oracle11gR2 Aactive DataGuard(手动)安装部署及维护文档(三)之升级及rman l 第六部分: dataguard其它管理问题一．滚动升级DG 升级概要 ...
oracle adg维护,Oracle11gR2 Aactive DataGuard(手动)装配部署及维护文档（三）之升级及rman...
Oracle11gR2 Aactive DataGuard(手动)安装部署及维护文档(三)之升级及rman l 第六部分: dataguard其它管理问题一．滚动升级DG 升级概要 ...
服务器维护文档,ERP系统维护服务器维护管理文档.docx
文档介绍: ERP系统机箱及办事器治理维护文档作者: 数据技能组创建日期: 2013-05-08 修他日期: 版本: 1.0 目录目录 2 编写说明 3 使用东西 4 参考文档 4 图标说明 4 ...
团队协作之文档管理-ShowDoc本地化安装使用
文章目录 1. 文档分类 2. ShowDoc 简介 3. ShowDoc 本地安装及设置 4. ShowDoc 使用 5. 总结在团队协作中除了代码的版本管理之外,还有文档管理也是比较重要的,比如 ...
什么知识库工具适合小团队？看看文档管理系统+NAS的最新解决方案
编者按:还在为团队选那款网盘而发愁吗?试试文档管理系统和NAS结合吧,高效率低成本,适合小团队. 关键词:免维护,免安装,大容量,在线编辑,文档共享,数据安全对于企业或团队而言,知识库软件的目的就在 ...
微软语音AI技术与微软听听文档小程序实践 | AI ProCon 2019
演讲嘉宾 | 赵晟.张鹏整理 | 伍杏玲来源 | CSDN(ID:CSDNnews) [导语]9 月 7 日,在CSDN主办的「AI ProCon 2019」上,微软(亚洲)互联网工程院人工智能语 ...
Websocket 百万长连接技术，在石墨文档中的实践
今日推荐推荐一个 Java 接口快速开发框架干掉Random:这个类已经成为获取随机数的王者Docker + Intellij IDEA,提升 10 倍生产力!笑出腹肌的注释,都是被代码耽误的诗人! ...
微软语音 AI 技术与微软听听文档小程序实践 | AI ProCon 2019
演讲者 | 赵晟.张鹏整理 | 伍杏玲出品 | CSDN(ID:CSDNnews) [CSDN 编者按]9 月 7 日,在CSDN主办的「AI ProCon 2019」上,微软(亚洲)互联网工程院 ...
团队在线协作文档工具推荐
未来组织竞争的关键是关注人才,关注人才的关键是团队合作,团队合作的关键是合作效率,合作效率的关键是生产力工具.由此可见,工作中的协作效率与组织使用的文档高度相关,所以今天要分享的内容是可以在线协作的文 ...

技术团队如何维护文档

技术团队如何维护文档相关推荐

最新文章

热门文章