软件工程之美学习笔记十七 16 | 为什么你不爱写项目文档？

《软件工程之美》材料地址： https://time.geekbang.org/column/article/88606

为什么程序员都不爱写文档?

• 不知道怎么写
• 太忙没时间写或者懒得写
• 敏捷开发所以不用写文档
  敏捷从来没有否认文档的价值，只是更重视“工作的软件”罢了。

为什么要写文档？

• 帮助写文档的人理清楚思路
  先写文档，就会抛开代码细节，去站在全局思考。
  真正的障碍是没想清楚，在心中只有一些未成型的混乱的想法和概念，必须要努力把这些模糊的想法确定化和具体化，才能写出来。
• 便于未来的维护和交接
• 团队更好的协作沟通

如何写好文档？

1. 从模仿开始

2. 从小文档开始

3. 从粗到细，迭代更新
   写得越细则无用功越多，最后，你甚至会因为不想改文档而抵触不同的意见。

4. 一些基本的画图的技巧

   （1）线框图
   
   
   （2）流程图
   
   （3）时序图
   
   （4）其他截图

一些关于文档的其他建议

1. 文档很重要，但是工作的软件高于详尽的文档。这里面的平衡很重要。
2. 不需要为代码写很多文档，好的代码格式，良好的注释、完善的单元测试可以很大程度上代替针对代码而写的文档。
3. Markdown 是一种非常好的文档格式
4. 在线文档工具优于离线文档工具，在线文档有很好的版本管理，也更方便多人协作
5. 作为一个正规的项目任务进行，安排人、安排时间，放到项目计划中
6. 写的越多，就越熟练。

留言摘录

1. Bo:已经写好项目文档，但想更另一步优化文档，老师可以分享一下项目中需求规格说明书，概要设计，详细设计，代码规范文档，测试文档，部署文档等的优秀具体案例吗？特别想看看老师的，模仿学习？

作者回复: 有些内部文档不方便分享。

我在文中附了一个开源项目的链接：https://video-react.js.org/
这个是一个组件使用文档

其实类似的有很多开源项目的文档都写得很好。比如：
Vue: https://cn.vuejs.org/v2/guide/
Redux: https://redux.js.org/

还有可以网上搜索一些，例如：
产品需求文档模板：https://www.jianshu.com/p/e89e97858be1
微服务：从设计到部署：
https://docshome.gitbooks.io/microservices/content/2-using-an-api-gateway.html

2. hua168
   老师，你能简单说一下项目前–>项目中–>项目完成，一般都需要哪些文档呀，有没有示例或链接或搜索关键词？好让我们没有项目经验的，能见识一下

作者回复: 我大致列一下，可能有遗漏的：
项目立项：

原始需求文档
可行性分析报告
立项说明书

需求相关的：
原型设计文档
产品设计文档

系统设计相关的：
技术方案文档
详细设计文档

开发相关的：
代码规范文档

测试相关的：
测试用例
测试验收报告

运维相关的：
部署文档
故障报告

其实没有特别的标准的，还是根据各个阶段需要。原则上就是：

1. 这件事需要讨论需要评审，要有文档作为讨论的依据，以及记录讨论的结果。比如各种设计文档
2. 这件事要有规范，要有文档保证规范统一。比如各种规范文档
3. 这件事要记录下来，作为以后的一个参考。比如各种报告、环境配置、操作手册、API文档等