我个人比较倾向于敏捷的方式，不赞同大而全的文档，因为那样的文档书写起来浪费时间，维护起来更浪费时间，更可怕的是没有持续更新导致文档与实际项目偏差很大的文档。所以我认为文档就是应该少而精，必须确保文档的持续更新才有价值，具体的细节让代码去说，当然代码本身要写的可读性高。

    今天和项目管理人员讨论了一下，我觉得分为如下几种情况：

1. 正规立项的项目：那个当然要安装立项你当时承诺的给文档。我建议是
  1）如果有需求分析阶段，那必须要出一个文档来记录这段时间的工作；
  2）架构设计文档是必须的，因为在代码中是很难直观看到整体的系统设计；
  3）概要设计、详细设计什么的我都不知道是想干什么，如果是说代码的具体实现，那就到代码中去看，没必要维护这个文档；
  4）测试文档：这个比较尴尬，这个应该是测试人员编写的，但是我们现在的情况是自己测试，那么有测试就要有记录，把测试的预期、测试的结果、测试的结论要写清楚就行了，格式可以不限；
  5）数据库设计文档：我个人认为这个写文档完全没意义，在架构设计中把数据库表结构的关联关系说明即可，工程目录下的db目录里面必须有当前版本的建表语句，这样就足够了。
  6）这个开发完的系统每次发布必须要有基线，release的版本要入库。

2. common下的公共模块或小系统：因为系统比较简单，所以可以简化一下。我建议是
  1）要有简单的架构设计说明
  2）要有简单的功能说明
  3）要有使用说明，这个可以用测试类来代替，在使用说明上写一下看哪些测试类就可以了
  4）这个开发完的模块需要有基线，并且要入库。
  其中这三个说明都直接写在一个readme文件中就可以了，该文件放在工程的doc目录下，可以方便的查阅。

3. example下的示例系统：这个就是个简单的例子，没有完整的系统功能，所以文档方面同common要求即可，readme放在工程的doc目录下。这个系统只需有基线，不用入库走那么麻烦的流程。

    以上系统都必须有changelog的说明文档，这个是能随包发布的，也可以非常清晰的看到历史改动以及版本变迁。写changelog我认为是一个非常好的习惯，不管有没有release note的管理。

本文转自passover 51CTO博客，原文链接：http://blog.51cto.com/passover/566377，如需转载请自行联系原作者