程序员该怎样写文档？

程序员该怎样写文档？

文档的重要性

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

开发前的设计文档

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

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

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

使用文档、自测文档

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

怎么写文档呢？

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

写文档的套路

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

描述原则

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

其他原则

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

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