程序员该怎样写文档?

程序员该怎样写文档?

文档的重要性

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

开发前的设计文档

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

开发过程中不断完善的详细设计文档

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

使用文档、自测文档

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

怎么写文档呢?

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

写文档的套路

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

描述原则

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

其他原则

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

另外:本文是文章,不是文档,所以不要用“文不如表,表不如图”这句话来做杠精。

版权声明

弈心博客


首发 弈心博客,转载请附链接!

赞赏支持

感谢支持!


建站不易,感谢支持!

推荐阅读
Python 使用requests发送POST请求 这两天开发,经常用到后端访问别的接口,所以看了一下 ,后端发送请求,这里总结一下1 ----------以form形式发送post请求#定义访问的登录网址url = 'http://httpbin.org/post'#配置需要的数据 d = {'key1': 'value1', 'key2': 'value2'}@发送请求 r = requests.post(url, data=d)#打印返回结果
225

操作系统题 一.选择题 1.若操作系统文件管理程序正在将修改后的____文件写会磁盘时系统发生崩溃,对系统的影响较大。 A.用户数据 B.用户程序 C.系统目录 D.空闲块管理 2.通常所说的I/O设备是指( )。 A.输入输出设备 B.通信设备 C.网络设备 D.控制设备 3. 操作系统在计算机与用户之间起____的作用。 A.传输 B.接口 C.连接 D.支撑 4. 文件系统
819

TP6 常用变量 请求变量use think\facade\Request; Request::param('name'); Request::param();全部请求变量 返回数组 Request::param(['name', 'email']); 多个变量 Request::param('a','1') $a不存在使用默认值1 Request::param('username','','strip_tags'
277

V模型 介绍V模型和瀑布模型有一些共同的特性,V模型中的过程从左到右,描述了基本的开发 过程和测试行为。说明单元测试:是模块测试,验证软件的基本组成单位的正确性,是白盒测试集成测试:是模块间的测试,测试接口(软件各模块之间的接口和软件与硬件之间的接口)是否正确,是灰盒测试(白盒和黑盒结合)系统测试:系统测试包括:冒烟测试 系统测试 回归测试冒烟测试:主干流程测试,确认软件的基本功能正常,可以进行后续的测试
929

MVC【简介,母版页,流程】 1,MVC是什么? MVC是一个全新的Web应用框架 MVC是基于asp.NET的应用框架,就是ASP.NET 的MVC设计模式 可能你们又会问什么是asp.NET了,这个简单的理解就是微软公司开发的web,也就是网站的开发平台。只不过加入MVC之后,他会主动帮你做好一些东西,让你的编写代码变得更加的简单,省力。 2,MVC的构成? 由模型(Model),视图(View),控制器(Contro
291

解决修改CSS文件后网页显示不生效问题 刚开始学CSS,HTML+CSS+Div虽说是上个世纪就有产生的发明,但我却不会。不过,不要紧,学就是了。 问题是这样的: 我编写HTML文件,并调用CSS文件实现布局美化。然后,经常出现明明已经修改过CSS文件 但 HTML页面却并没有产生变化的现象。 怎么办? ##CSS语法 作为初学者,首先想到的时自己写错了。所以查找正确的语法,如这一文章中提到的[HTML调用CSS管理、美化div](
1234

程序员该怎样写文档? 程序员该怎样写文档? ### 文档的重要性 在开发流程中的每一个阶段,文档都很重要。 ### 开发前的设计文档 在开始Coding前,应先完成设计文档。 设计文档包括需求分析、概要设计、架构图(模块功能图)、主要API的定义设计和当前开发任务的大体业务流程。 设计文档的意义是在开发前将输出成果的未来式在产品经理、项目经理和架构师的脑海中达成共识。通过Review设计文档的工作模式,将产品相关的
1632

H5网页游戏引擎Phaser 3 Hello World 起步指南 官网文档笔记【一】 H5网页游戏引擎Phaser 3 Hello World 起步指南 官网文档笔记【一】 官网:http://phaser.io/tutorials/getting-started-phaser3 1、安装web服务器,apache或者nginx都可以 配置完成后,需要浏览器在 http://localhost 查看一下,确保服务搭建成功。 2、安装环境, 其实就是下载JS包 3、编辑器
1215

盘点知乎那些做起来无聊但坚持越久意义越大的事【二】 它山之石可以攻玉,向优秀的人学习,或者说善于吸收他人的经验教训,对自己的成长有莫大裨益。 本文盘点知乎那些做起来无聊但坚持越久意义越大的事【二】 ### 传送门 [盘点知乎那些做起来无聊但坚持越久意义越大的事【一】](http://www.yixzm.cn/index/reading/article/story/299) 正文开始 ### Jimmy.Y 圣安德鲁斯大学 金融学硕士 ~1. 锻炼
4378

2020,再见;2021,我来了! 现在是2021年1月16日下午16点33分,星期六。此时北京正在通报昨日新冠肺炎新增病例情况,这种每天戴口罩的鬼日子还不知道什么时候能结束。最近由于天气变冷,病毒更容易存活和传播,最近一个月就突然又变的非常紧张起来了,几乎隔一段时间公司人力就会在群里统计有没有到过哪哪哪中高风险地区。尤其是我的家乡河北更是成了这次病毒肆虐的重灾区,我每天也是都在关注新闻和老家亲人们的消息和进展,希望疫情能尽快结束吧
710

thinkphp6报错 {"code":0,"message":"页面错误!请稍后再试~"} ## 报错 {"code":0,"message":"页面错误!请稍后再试~"} ## 原因 thinkphp code 0, controller变量大小写引起的问题 ## 详情 比如,这个错误发生的场景是这样的: windows开发环境,controller不区分大小写,上传后接口请求大小写敏感,如果
1001

Web前端开发工程师面试(2020-9-15 面试笔试题目及回答思路指南) 面试题来自某互联网独角兽公司的前端开发工程师岗位面试记录,刚打听到的还很新鲜。 面试官和面试者小编都挺熟悉,所以内容具备一定参考价值。 面试中夹杂笔试,整个过程流程大体如下: ### 1 Q:简单做下自我介绍 A:这里是在问前端技术路线、技术面、技术成长规划,别有的没的讲一堆废话。 ### 2 Q:离职原
1160