程序员该怎样写文档?

程序员该怎样写文档?

文档的重要性

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

开发前的设计文档

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

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

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

使用文档、自测文档

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

怎么写文档呢?

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

写文档的套路

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

描述原则

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

其他原则

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

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

版权声明

弈心博客


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

赞赏支持

感谢支持!


建站不易,感谢支持!

推荐阅读
Git for windows 修改Home路径(版本号:2.14) 前人留下的网络资料有解决1.9版本的这个问题,但对2.14版本已经不再适用。前人资料:http://www.cnblogs.com/fenpho/p/6208896.htmlhttp://www.cnblogs.com/xunzhiyou/p/5028789.html实际操作后,修改/etc/profile文件后,重新开始GitBash并没有生效。由于Git的默认路径在C:\Users\Admin
159

thinkphp6设置Content-type解决header添加不生效问题 thinkphp6设置Content-type解决header添加不生效问题原生php只需要加入header就可以实现输出各种格式的文件内容,如header("Content-type:text/css");然而,在thinkphp6中却不能生效。response总会自动的将内容以网页的形式输出。即自动添加<html>、<body>等标签,无法达到预期的效果。tp6框架中提
3982

【Gtest(Google Test)帮助手册】en-cn Gtest官方使用文档英文文档获得方式:框架生成的执行文件,在命令行--help即可获得。中文翻译版本操作文档只对使用Gtest(GoogleTest)开发的测试用例有效。通过命令,你可以使用以下功能:选择测试用例: --gtest_list_tests列出所有的测试用例,但并不执行。代码中的用例TEST(Foo,Bar)显示出的结果是"Foo.Bar".  --gtest_f
1888

每天上班都像上坟一样难受,怎么办?三条妙招让上班像踏青 经常听到身边有些朋友抱怨,说每天上班的心情就想上坟。然而,真是如此么?小编相信,每位上班像上坟的朋友,身边不会缺少这样的朋友:每天上班精神抖擞,很有干劲,心情愉悦就像是来踏青一样。他们是怎么做到的呢?其实,上班不愉快无非就是上班时心情不好,感觉焦虑。要知道,这些都是可以解决的!人的一生,就是适应、利用、创造法则的一生。法则就是自然法则、社会秩序和公司规章制度。最无力的时候只能去学习、适应法则,成长
2619

CSDN-markdown编辑器示意效果 欢迎使用Markdown编辑器写博客本Markdown编辑器使用StackEdit修改而来,用它写博客,将会带来全新的体验哦:Markdown和扩展Markdown简洁的语法代码块高亮图片链接和图片上传LaTex数学公式UML序列图和流程图离线写博客导入导出Markdown文件丰富的快捷键快捷键加粗Ctrl+B斜体Ctrl+I引用Ctrl+Q插入链接Ctrl+L插入代码Ctrl+K插入图片Ctrl
1231

php开发遇到的Access denied for user php开发遇到的Accessdeniedforuser'root'@'localhost'(usingpassword:NO)首发:2017-09-2413:44:38环境:CentOS6.5+php5.3.3在php开发过程中,我遇到了一个问题:在命令行中登录Mysql完全正常,然而PHP代码读取数据库却出了问题。报错如下:Accessdeniedforuser'root'@'localhost
2934

Linux环境C C++起Socket Server监听8080端口的代码实现 代码抄录自《UNUX网络编程卷一》,在实现开发环境中调试通过,经测试发现可以正常监听。(2017-09-0621:56:31)开发环境:CentOS,g++,VIM功能:C++实现Socket通信的Server端,实现监听8080端口接收到的消息。#include#include/*SeeNOTES*/#include#include#include#include#include#include
2488

CentOS 系统简易搭建FTP服务(四步足矣) 本文作者之前在CSDN发过(2017-09-0313:09:28),现在入驻本站。网上有很多的FTP搭建步骤,但普遍很繁琐,个人临时使用太麻烦。本次实验使用腾讯云服务器CentOS简易搭建FTP服务器,四行命令足矣完成基本使命。yuminstallvsftpdservicevsftpdstartuseradd-m-d/home/uftp-s/sbin/nologinuftppasswduftp目前
2323

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

linux中查看C C++程序或调用其中某个函数(类)消耗内存的方法实现 验证C/C++程序或调用其中某个函数(类)消耗内存的方法:获取进程ID,调用/proc/[pid]/status查看消耗的内存页(4KB/内存页)进程ID获取方法UNIX环境高级编程中提到的getpid(),可以获取。头文件``查看内存信息sprintf(FILE_NAME,"/proc/%d/statm",pid);FILE*fp=fopen(FILE_NAME,"r");fscanf(fp,"
2278

Linux(Android)系统Root实现原理 方案主旨思想是查找系统漏洞,让本身具有root权限的进程执行打开root权限的操作。重烧engboot.img方案Android版本有user版本和eng版本的区别,其中eng版本可以用于开发调试,所以本身可以开启root权限。通过重烧engboot.img版本来获取root权限。这个原理理解起来很简单,原理章节不再详述。死锁问题root需要考虑两个问题:(1)root权限的获取;(2)root权
2729

Ubuntu中Apache2启动失败报错Job for apache2.service failed because the cont... Ubuntu中Apache2启动失败报错Jobforapache2.servicefailedbecausethecont...为解决这个问题,花了一个下午,参考了120多条网络博文,很有成就感。但实际上是由于一个简单的配置原因导致的问题,希望以后可以更加细心。-最初的现象,php代码没有解析phpinfo输出内容是显然,只是代码,并没有成功解析php代码。事后分析,是Apache2服务的问题。-
3076