项目文档管理的一些想法-阿里云开发者社区

开发者社区> 数据库> 正文

项目文档管理的一些想法

简介:

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

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

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,如需转载请自行联系原作者

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
数据库
使用钉钉扫一扫加入圈子
+ 订阅

分享数据库前沿,解构实战干货,推动数据库技术变革

其他文章