研发过程中的文档管理与工具

写文档也是技术活。

—1—

实践

对于多数开发同学来说，很多时候即讨厌没有研发文档，但是自己又不愿意常写文档，痛且倔强着。

程序员该不该写文档，与争论哪种编程语言最好一样，想撕的嘴不留情，该写的笔不停耕。

当自我的意识上去纠结一件事情要不要去做的时候，不妨停下来看一看，大的职场环境是如何选择的，纠结自然就没必要了。

对于写文档这件事情，并不需要去思考能带来哪些好处或者会占用多少时间，用心去写自然明白当中利弊。

最近两年听到不少搬砖的朋友说，公司已经把文档管理提升到资产层面，在重大版本推进过程中，预留文档输出的时间，这可不是一般的大聪明。

从工作的这几年实践经验来看，写文档原则上本着复杂的事项细写，简单的事项简写或者不写，卷可以但又不闲的慌。

—2—

互联网的产品，多少存在一定的虚拟属性，很多事情和想法也都具有明显的抽象感，如果缺乏文档的结构化描述，时间拉扯下很容易烟消云散。

这里罗列一份在研发管理和职场中，或多或少都会接触到的文档内容，虽然结构复杂，但随着时间的沉淀，其带来的价值远大于维护成本。

工作中涉及到的文档种类比较繁多，但就管理和沉淀的动作来说属于那种重要但不紧急的事情，这样说并不是指研发流程中动作的时序可以混乱。

顺着工作流程把该输出的文档做好，是比较正常的节奏，在特殊情况下也可以先解决事情，再后补文档。

从开发的角度来说，如果是常规状态下的版本推进，那么在版本结束时各种相关文档就可以上传指定目录了。

但是工作中不乏很多生产环境突发的棘手状况，此时团队自然优先解决，如果问题影响过大，在事后必然还要输出总结文档，即是经验更是教训。

—3—

模板

如果是个人的文档，简明扼要即可；但是工作文档需要有规范和风格上的约束，通常情况下基于统一的模板库即可。

在研发流程中，通常会围绕项目的进度管理文档，在该文档中会统筹流程中的核心内容，涉及各个阶段的进度维护。

基于项目进度管理的文档模板，在流程推进的过程中，不断补齐相关的核心内容，清晰准确的记录版本进度。

采用特定的模板写工作文档，本身就会起到规范的效果，在部门的日常管理中，需要阶段性的沉淀和维护各类文档的模板结构，而模板的内容可以根据具体需求来定，在使用的过程中也需要时常优化。

如果文档模板足够丰富，在一定程度上可以解决不想写文档的问题，在写文档这件事上之所以会劝退很多人，很大原因是缺少可用的文档模板。

当模板库中存在：项目进度、研发设计、测试用例、阶段总结、阶段规划等各种样例时，下载之后直接使用，编写核心内容即可，这样排斥写文档的情绪自然减少。

—4—

内容

文档的内容是价值所在，对于团队的协作来说内容简明扼要即可，让阅读文档的人可以快速准确的理解事情的信息。

通常需要输出文档的事项都比较复杂，所以在内容上需要适当的排版，复杂的逻辑尽量使用图解来描述，这样内容条理和思路都会很清晰。

对于其他细节方面的把控，比如段落缩进、专业名词、空格等，通常本着：对内的文档尽量做好，对外的文档必须做好的原则。

文档内容是思考逻辑的呈现，在编写过程中也容易发现逻辑上的问题，再通过评审讨论和完善内容，这样事情围绕文档在后续的过程中不会过度偏离主线。

对于开发这个角色来说，写文档是避不开的事，在一个项目上待的时间久了，再看初期的代码，都觉得不是自己写的，更别说是复杂的业务逻辑了。

在研发文档中，最常用的图解就是逻辑时序，再适当的丰富相关的内容，在一份图中可以包括流程、逻辑、交互、数据管理等各个核心节点。

开发的设计文档基本是几张图就可以描述清楚的，通常涉及：业务流程图，逻辑时序图，数据结构图。

当复杂的业务呈现在文档和设计图上时，其实就是给事情预设好了航线，当然有时候中途被迫返航或变道也不少见。

—5—

工具

工欲善其事，必先利其器，想快速做好一份文档，必须得有趁手好用的工具才行，在多年写文档的经验中，以下工具多少都试用过。

图中标红的工具，是个人在实践中觉得不错的工具，当下使用最多的是DrawIO和语雀文档，在免费的边界内足够日常使用。

由于工作中需要对接的事项比较多，很难统一协作的各方使用的文档工具，自然接触到的工具类型就很复杂，对于团队内部来说，通常使用办公软件集成的工具，以便于统一管理。

写文档的习惯已经持续了很多年，工具的变迁也经历了三次，从办公文档迁向Markdown，从线下迁移到线上，更换过一次文档工具。

时间在变，文档类产品也在不断的更新换代，如何寻找自己顺手的工具，本着一个基本的原则：免费的范畴内，支持在线管理，功能适当丰富即可。

最后分享一条写文档的理由：因为工作多而复杂，所以要写到文档中，这样便能安心的忘了它。

本文源自公众号知了一笑，分布式实验室已获完整授权。