4、文档常见问题

  (1)文档编写不够规范。主要表现在软件项目实施过程中,没有对每一个阶段的文档进行整理,分层次管理,各类文档资料缺少一个可以参照的样本,更多的是在以前他人写好的基础上,对内容进行修改一下算完成任务。

  (2)文档内容描写不够完善。在编写各种文档过程中,虽然大家都按事先规定的模式进行了编写,但编写的内容经常不够完善,夹杂着一些旧的东西没有及时更新。特别是一些参数表、用户手册等一些由数据中心、分行使用的文档,由于一时的疏漏,造成软件项目投产失败、投产后造成系统宕机、出现账务差错、客户按照你的操作说明不能得到正确的结果等现象的发生。

  (3)对文档评审不够,使用效果不理想。按照软件工程的要求,在软件项目的开发过程中从设计到投产,要编写一系列的文档,编写这些文档是必须的,但经常会出现这样的现象,在软件开发企业,某职能部门负责人员自行制定了文档模板后,通知各部门进行使用,结果大家反映效果不好,分析原因是没有在编写时很好地依据企业自身的现状,从实际出发征求大家的意见,对投入使用的文档没有组织相关人员进行评审。

  (4)重视文档的形式,实用性不强。在实际的软件开发过程中,要求编制的文档非常多,但编制人员没有时间去关心它们的用途,也不知道哪些部门使用,更多的是在规定的时间内完成任务,以免影响考核成绩,这样一来一些不实用的、重复的文档编制工作,占用了开发人员有效的设计开发时间,影响了项目的整体进度。因此,软件文档的制定要实用,减少繁文缛节的文字工作。

  (5)文档没有统一入库管理。随着系统的不断优化、升级,新需求的不断产生,各种文档越来越多,没有建立一个文档资料信息库,统一存放软件项目不同时期的各种文档,零散存在的文档,造成查询、统计一个软件项目完整的文档信息时非常困难。

  (6)对文档的编制重视不够。大家常常把文档作为软件产品的附件,对待文档资料没有像对待程序代码一样关注和投入,文档中普遍存在错别字、语句涵义表达不清楚,口语化浓厚,引用的图表不够准确,主题表达不够清晰等现象。

  (7)对文档的测试不足。通常测试主要是针对软件项目功能的测试,对该软件项目的文档测试则很少进行。通常用户把文档当成了软件产品的一部分,在软件产品安装使用过程中,不正确的提示信息把客户引入歧途,不但得不到预期的结果,还会产生错误,给用户带来麻烦。

  5、文档编制要求

  (1)标准化:从需求分析开始到投产应用所有涉及的每一种文档,都要给出一个可以执行的模板,所有完成的文档从里到外都要非常工整,具有专业水准,符合ISO9000及CMM质量标准要求。

  (2)易用性:编制的各种软件文档,要便于不同的岗位人员进行阅读、理解、学习和使用。

  (3)简洁性:要求软件项目中需要编写的文档内容突出主题,只反映要描述的问题,不包含其他不必要的东西,语言表达简明扼要,一清二楚,如有可能,可以配以适当的图表,以增强其清晰性。

  (4)针对性:文档要按不同的类型、面对不同的对象,实行差异化编制,根据实际需要进行编写,也是说文档编写目的要明确,因需而变。例如管理文档主要面向管理人员,用户文档主要面向用户,这两类文档不应像开发文档(面向开发人员)那样过多使用软件的专用术语。

  (5)一致性:文档的行文应当十分确切,对于同一现象的描写,不能出现多义性的描述,同一项目中几个文档描述的内容应当是一致的,相互之间没有矛盾。

  (6)完整性:任何一个文档都应当是完整的、独立的,没有遗漏和丢失的内容。也是说每一种文档在设计时可以包含必要的图形、模型、叙述、表、索引、附录和参考文献,列举的这些内容都是完整的。同一软件项目涉及的几个文档之间可能存在部分内容相同,这种重复是必要的,不要在文档中出现“见XX文档XX章节”的现象。