写文档也是技术活
01：实践
对于多数开发同学来说，很多时候即讨厌没有研发文档，但是自己又不愿意常写文档，痛且倔强着；
程序员该不该写文档，与争论哪种编程语言最好一样，想撕的嘴不留情，该写的笔不停耕；
当自我的意识上去纠结一件事情要不要去做的时候，不妨停下来看一看，大的职场环境是如何选择的，纠结自然就没必要了；
对于写文档这件事情，并不需要去思考能带来哪些好处或者会占用多少时间，用心去写自然明白当中利弊；
最近两年听到不少搬砖的朋友说，公司已经把文档管理提升到资产层面，在重大版本推进过程中，预留文档输出的时间，这可不是一般的大聪明；
从工作的这几年实践经验来看，写文档原则上本着复杂的事项细写，简单的事项简写或者不写，卷可以但又不闲的慌；
02：目录
互联网的产品，多少存在一定的虚拟属性，很多事情和想法也都具有明显的抽象感，如果缺乏文档的结构化描述，时间拉扯下很容易烟消云散；
这里罗列一份在研发管理和职场中，或多或少都会接触到的文档内容，虽然结构复杂，但随着时间的沉淀，其带来的价值远大于维护成本；
工作中涉及到的文档种类比较繁多，但就管理和沉淀的动作来说属于那种重要但不紧急的事情，这样说并不是指研发流程中动作的时序可以混乱；
顺着工作流程把该输出的文档做好，是比较正常的节奏，在特殊情况下也可以先解决事情，再后补文档；
从开发的角度来说，如果是常规状态下的版本推进，那么在版本结束时各种相关文档就可以上传指定目录了；
但是工作中不乏很多生产环境突发的棘手状况，此时团队自然优先解决，如果问题影响过大，在事后必然还要输出总结文档，即是经验更是教训；
03：模板
如果是个人的文档，简明扼要即可；但是工作文档需要有规范和风格上的约束，通常情况下基于统一的模板库即可；
在研发流程中，通常会围绕项目的进度管理文档，在该文档中会统筹流程中的核心内容，涉及各个阶段的进度维护；
基于项目进度管理的文档模板，在流程推进的过程中，不断补齐相关的核心内容，清晰准确的记录版本进度；
采用特定的模板写工作文档，本身就会起到规范的效果，在部门的日常管理中，需要阶段性的沉淀和维护各类文档的模板结构，而模板的内容可以根据具体需求来定，在使用的过程中也需要时常优化；
如果文档模板足够丰富，在一定程度上可以解决不想写文档的问题，在写文档这件事上之所以会劝退很多人，很大原因是缺少可用的文档模板；
当模板库中存在：项目进度、研发设计、测试用例、阶段总结、阶段规划等各种样例时，下载之后直接使用，编写核心内容即可，这样排斥写文档的情绪自然减少；
04：内容
文档的内容是价值所在，对于团队的协作来说内容简明扼要即可，让阅读文档的人可以快速准确的理解事情的信息；
通常需要输出文档的事项都比较复杂，所以在内容上需要适当的排版，复杂的逻辑尽量使用图解来描述，这样内容条理和思路都会很清晰；
对于其他细节方面的把控，比如段落缩进、专业名词、空格等，通常本着：对内的文档尽量做好，对外的文档必须做好的原则；
文档内容是思考逻辑的呈现，在编写过程中也容易发现逻辑上的问题，再通过评审讨论和完善内容，这样事情围绕文档在后续的过程中不会过度偏离主线；
对于开发这个角色来说，写文档是避不开的事，在一个项目上待的时间久了，再看初期的代码，都觉得不是自己写的，更别说是复杂的业务逻辑了；
在研发文档中，最常用的图解就是逻辑时序，再适当的丰富相关的内容，在一份图中可以包括流程、逻辑、交互、数据管理等各个核心节点；
开发的设计文档基本是几张图就可以描述清楚的，通常涉及：业务流程图，逻辑时序图，数据结构图；
当复杂的业务呈现在文档和设计图上时，其实就是给事情预设好了航线，当然有时候中途被迫返航或变道也不少见；
05：工具
工欲善其事，必先利其器，想快速做好一份文档，必须得有趁手好用的工具才行，在多年写文档的经验中，以下工具多少都试用过；
图中标红的工具，是个人在实践中觉得不错的工具，当下使用最多的是DrawIO和语雀文档，在免费的边界内足够日常使用；
由于工作中需要对接的事项比较多，很难统一协作的各方使用的文档工具，自然接触到的工具类型就很复杂，对于团队内部来说，通常使用办公软件集成的工具，以便于统一管理；
写文档的习惯已经持续了很多年，工具的变迁也经历了三次，从办公文档迁向Markdown，从线下迁移到线上，更换过一次文档工具；
时间在变，文档类产品也在不断的更新换代，如何寻找自己顺手的工具，本着一个基本的原则：免费的范畴内，支持在线管理，功能适当丰富即可；
最后分享一条写文档的理由：因为工作多而复杂，所以要写到文档中，这样便能安心的忘了它。
END
标签：逻辑,研发,内容,文档,工具,模板 来源： https://www.cnblogs.com/cicada-smile/p/16537287.html
本站声明： 1. iCode9 技术分享网（下文简称本站）提供的所有内容，仅供技术学习、探讨和分享； 2. 关于本站的所有留言、评论、转载及引用，纯属内容发起人的个人观点，与本站观点和立场无关； 3. 关于本站的所有言论和文字，纯属内容发起人的个人观点，与本站观点和立场无关； 4. 本站文章均是网友提供，不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属；如您发现该文章侵犯了您的权益，可联系我们第一时间进行删除； 5. 本站为非盈利性的个人网站，所有内容不会用来进行牟利，也不会利用任何形式的广告来间接获益，纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。