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

原文地址：https://mp.weixin.qq.com/s/0CFV-ekcyZJ0gHKTSdTnMg 公众号：知了一笑

1 目录

互联网的产品，多少存在一定的虚拟属性，很多事情和想法也都具有明显的抽象感，如果缺乏文档的结构化描述，时间拉扯下很容易烟消云散；
这里罗列一份在研发管理和职场中，或多或少都会接触到的文档内容，虽然结构复杂，但随着时间的沉淀，其带来的价值远大于维护成本；

工作中涉及到的文档种类比较繁多，但就管理和沉淀的动作来说属于那种重要但不紧急的事情，这样说并不是指研发流程中动作的时序可以混乱；
顺着工作流程把该输出的文档做好，是比较正常的节奏，在特殊情况下也可以先解决事情，再后补文档；
从开发的角度来说，如果是常规状态下的版本推进，那么在版本结束时各种相关文档就可以上传指定目录了；
但是工作中不乏很多生产环境突发的棘手状况，此时团队自然优先解决，如果问题影响过大，在事后必然还要输出总结文档，即是经验更是教训；

2 模板

如果是个人的文档，简明扼要即可；但是工作文档需要有规范和风格上的约束，通常情况下基于统一的模板库即可；
在研发流程中，通常会围绕项目的进度管理文档，在该文档中会统筹流程中的核心内容，涉及各个阶段的进度维护；

基于项目进度管理的文档模板，在流程推进的过程中，不断补齐相关的核心内容，清晰准确的记录版本进度；
采用特定的模板写工作文档，本身就会起到规范的效果，在部门的日常管理中，需要阶段性的沉淀和维护各类文档的模板结构，而模板的内容可以根据具体需求来定，在使用的过程中也需要时常优化；
如果文档模板足够丰富，在一定程度上可以解决不想写文档的问题，在写文档这件事上之所以会劝退很多人，很大原因是缺少可用的文档模板；
当模板库中存在：项目进度、研发设计、测试用例、阶段总结、阶段规划等各种样例时，下载之后直接使用，编写核心内容即可，这样排斥写文档的情绪自然减少；

3 内容

文档的内容是价值所在，对于团队的协作来说内容简明扼要即可，让阅读文档的人可以快速准确的理解事情的信息；
通常需要输出文档的事项都比较复杂，所以在内容上需要适当的排版，复杂的逻辑尽量使用图解来描述，这样内容条理和思路都会很清晰；
对于其他细节方面的把控，比如段落缩进、专业名词、空格等，通常本着：对内的文档尽量做好，对外的文档必须做好的原则；
文档内容是思考逻辑的呈现，在编写过程中也容易发现逻辑上的问题，再通过评审讨论和完善内容，这样事情围绕文档在后续的过程中不会过度偏离主线；
对于开发这个角色来说，写文档是避不开的事，在一个项目上待的时间久了，再看初期的代码，都觉得不是自己写的，更别说是复杂的业务逻辑了；

在研发文档中，最常用的图解就是逻辑时序，再适当的丰富相关的内容，在一份图中可以包括流程、逻辑、交互、数据管理等各个核心节点；
开发的设计文档基本是几张图就可以描述清楚的，通常涉及：业务流程图，逻辑时序图，数据结构图；
当复杂的业务呈现在文档和设计图上时，其实就是给事情预设好了航线，当然有时候中途被迫返航或变道也不少见；

4 工具

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

图中标红的工具，是个人在实践中觉得不错的工具，当下使用最多的是DrawIO和语雀文档，在免费的边界内足够日常使用；
由于工作中需要对接的事项比较多，很难统一协作的各方使用的文档工具，自然接触到的工具类型就很复杂，对于团队内部来说，通常使用办公软件集成的工具，以便于统一管理；
写文档的习惯已经持续了很多年，工具的变迁也经历了三次，从办公文档迁向Markdown，从线下迁移到线上，更换过一次文档工具；
时间在变，文档类产品也在不断的更新换代，如何寻找自己顺手的工具，本着一个基本的原则：免费的范畴内，支持在线管理，功能适当丰富即可；