程序员该怎样写文档?

程序员该怎样写文档?

文档的重要性
在开发流程中的每一个阶段,文档都很重要。

开发前的设计文档
在开始Coding前,应先完成设计文档。
设计文档包括需求分析、概要设计、架构图(模块功能图)、主要API的定义设计和当前开发任务的大体业务流程。
设计文档的意义是在开发前将输出成果的未来式在产品经理、项目经理和架构师的脑海中达成共识。通过Review设计文档的工作模式,将产品相关的各个角色的意见和建议融入产品设计图。
如果没有意外,在实际开发将严格按照设计文档的约定执行。
如果实现的时候,因技术实现成本等原因一定要更改最初的设计,则尽可能以与设计文档达成一致作为开发目标。

开发过程中不断完善的详细设计文档
在Coding过程中,经过测试、Debug、需求变更和一次次的迭代,产品的实现与设计文档最初的设计会存在偏差。所以,在开发过程中需要经常将实际产品与设计文档对标。
例如:API会随着迭代的推进增加数量。
在开发过程中,如果因人力成本等原因无法兼顾到详细设计文档的更新,那在开发工作完成后一定要回溯、补全详细设计文档。详设文档对工程后续的维护升级有着重要的意义。

使用文档、自测文档
开发完毕后,需编制项目(功能模块)的使用文档。
在理想化的场景,开发成果的使用方式应当是与产品经理预言的使用方式是一致的。
开发人员在心里一定要有一个概念:一切开发工作都是在为用户服务。
通常开发人员的成果会被测试人员做系统化的测试。
在交付给测试人员前,开发人员需要根据成果所具备的功能提供对应的测试用例Demo,目的是起码要保证Demo用例能够通过,然后才可能经得起测试人员甚至用户的测试。

怎么写文档呢?
对大多数开发人员而言,写文档都是一件极其麻烦的事情。
但实际上,写文档要比写代码容易的多。

写文档的套路
技术文档的核心套路是:
讲清楚开发成果是做什么的,怎么做,怎么用,使用示例是什么就可以了。
以一个灯泡为例:
灯泡用来照明,安装在灯架里并通电,开关决定是否照明,伸手操作开关(+配图)
这样,一个灯泡的文档框架或者说0.1版本就OK了。

描述原则
在实际写文档的时候,一定要具体。
优秀的文档就是能让读者轻松的学会怎样用产品,后续维护者轻松的升级更新。
但怎样描述才算具体呢?
曾经看到的某段言论:
当你坐下来写作的时候,请记住,不是“一杯饮料”而是“一杯马丁尼”;不是“一只狗”而是“一只长卷毛狗”;不是“一束花”而是“一束玫瑰”;不是“一个滑雪者”而是“一位含苞欲放的年轻少女”;不是“一顶帽子”而是“一只高顶回角帽”;不是“一只猫”而是“一只阿比西尼亚猫”;不是“一支枪”而是“一支0.44口径的新式自动手枪”,不是“一幅画”而是一幅“马奈的‘奥林匹亚’”。
上面这段话虽然是针对写小说,但讲述的道理写文档时同样适用。
比如:不是“一台服务器”,而是“服务器(192.168.1.111)”;不是“编程语言”,而是“C语言或者Jave语言”;不是“一个变量”,而是“变量int serverCount = 0; ”

其他原则
在文档中,文不如表,表不如图。
能画一张表格讲清楚,就不要用一大段文字去啰里啰嗦表达。
能画一张图表达清楚,就不要用一大片表格让用户自己去分析。

另外:本文是文章,不是文档,所以不要用“文不如表,表不如图”这句话来做杠精。
————————————————
版权声明:本文为CSDN博主「弈心逐梦」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。
原文链接:https://yixzm.blog.csdn.net/article/details/84142496

版权声明

弈心博客


本文首发site_name,转载请附上博文链接!