人月神话5

5. 怎么写文档 P169
不同的用户需要的文档详细程度不同，具体的内容书中已经总结的很好了。

5.1. 怎么对待流程图
“逐一记录的详细流程图过时而令人生厌，它只适合启蒙初学者的算法思维”
我十分赞同这句话，流程图一般是用于理解代码用的，自己写的代码往往不需要先生成流程图。
有一个例外，我认为ER图、时序图 还是很好用的，并且是足够简单的时序图。在评审环节可以让评审人更直观的了解程序交互的系统、角色。在代码完成后绘制时序图曾让我看出代码质量不好的地方，并以出现简洁时序图为宗旨，最后把代码改造的更加可读。

5.2. 自文档化的程序
原则是代码的说明最后跟代码放在一起。所以有了 self-documenting 的说法。

规范
JavaDoc
语言
XML、Groovy DSL 本身就具有较高的可读性