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

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

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的管理。