写点什么

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

作者:知了一笑
  • 2022 年 7 月 31 日
  • 本文字数:1866 字

    阅读完需:约 6 分钟

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

写文档也是技术活


01:实践


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

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

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

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

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

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


02:目录


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

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



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

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

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

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


03:模板


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

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



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

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

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

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


04:内容


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

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

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

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

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



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

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

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


05:工具


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



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

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

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

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

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


END



发布于: 刚刚阅读数: 4
用户头像

知了一笑

关注

公众号:知了一笑 2020.04.08 加入

源码仓库:https://gitee.com/cicadasmile

评论

发布
暂无评论
研发过程中的文档管理与工具_Java_知了一笑_InfoQ写作社区