开发者社区> 知了一笑> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

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

简介: 从工作的这几年实践经验来看,写文档原则上本着复杂的事项细写,简单的事项简写或者不写,卷可以但又不闲的慌;
+关注继续查看
写文档也是技术活

01:实践


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

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

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

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

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

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

02:目录


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

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

01-1.png

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

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

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

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

03:模板


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

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

01-2.png

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

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

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

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

04:内容


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

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

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

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

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

01-3.png

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

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

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

05:工具


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

01-4.png

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

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

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

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

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

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
几种项目管理工具分享
几种项目管理工具分享
34 0
一个会“说话”的软件项目管理工具
“软件开发是一个需要高智力、频繁沟通和密切协作的过程。”
70 0
【项目管理工具】maven快速入土
【项目管理工具】maven快速入土
47 0
【SAP支持宝典】SAP传输管理系统快速诊断工具
【SAP支持宝典】SAP传输管理系统快速诊断工具 http://mp.weixin.qq.com/s?__biz=MjM5OTI2MjgyMA==&mid=208750119&idx=3&sn=c1b1d39700a9030...
1007 0
项目中如果管理前端文件CSS和JS
如何管理CSS和JS文件,一直是前端一个热门的话题。下面将简单分享一下使用心得,欢迎大家吐槽、拍砖和提供更好的实现方式。一、管理CSS文件,本博客将讨论less管理。iReset.less、iButton.less、iCss3.less、iIcon.less、iTab.less、iMenu.less、iDialog.less、iForm.less、iDatagrid.less等等文件、以上文件都是最小模块文件。
866 0
5个免费项目管理工具
1. Collabtive   Collabtive是一个基于Web的项目管理系统,非常知名的项目管理软件。提供的功能包括:项目管理,即时聊天工具,任务、文件管理,时间跟踪,多语言支持。 2. Freedcamp 这是另外一个免费项目管理领域的重量级的工具,功能全面,易于使用,有漂亮的UI。
1594 0
+关注
知了一笑
公众号:知了一笑
文章
问答
文章排行榜
最热
最新
相关电子书
更多
团队和工程管理取舍
立即下载
团队和工程管理的取舍
立即下载
码栈——让一切变得自动化
立即下载