文档编写技巧

10.1.2　文档编写技巧

随着计算机软件复杂性的提高，编制高质量的文档问题也变得日益迫切。软件文档作为软件不可分隔的有机组成部分，其一部分是软件过程中的中间工作产品，是评审的输入；另一部分则是软件产品的最终提交物，是项目验收的依据之一。好的软件文档能够起到多种桥梁的作用，有助于程序开发人员编写代码，有助于项目管理人员监督和管理软件的开发，有助于用户理解和使用软件。软件文档质量直接关系着软件的开发、使用、维护和交流等一系列工作。我国为了规范软件文档的编制，同时发布了GB/T8567－2006《计算机软件文档编制规范》的标准。软件企业在尽量采用和遵循现行的国家和国际标准的基础上，制定适合企业需求的文档建立的标准。

软件文档是软件开发和形成过程中非常重要的组成部分，因此编写出高质量的软件文档是软件开发中非常重要的工作内容。

首先，必须明确什么样的文档才是高质量的软件文档，一套高质量的软件文档体系一般具有如下的共同特性：

（1）全面性。软件文档体系中的文档应当涵盖了整个软件开发流程中所涉及的所有重要文档。

（2）针对性。文档编制前应分清和了解读者对象，根据读者的类型、层次和特点，来决定如何适应他们的要求。例如，开发文档主要是面向软件开发人员的，管理文档主要是面向管理人员，用户文档主要是面向用户，考虑到文档的读者需求，后两类文档不应像开发文档那样过多地使用软件的专业术语，以免造成读者的阅读困难。

（3）精确性。作为交流的载体，二义性文档导致的后果是灾难性的。因此，软件文档描述的内容应都是正确的、协调一致无二义性的。

（4）一致性。所有文档自身内容或相互之间以及产品描述之间都不应相互矛盾。每个术语的含义应完全保持一致。此外，在开发过程中，文档、需求、设计、代码的变更是在所难免的，软件文档也应与这些工作产品之间保持一致性。

（5）清晰性。文档编写应力求简明。在某些情况下，配以适当的图表，可以增强文档的清晰性。

（6）完整性。任何一个文档都应当是完整的、独立的，自成体系。一般来说，引言部分应作为一般性介绍，向读者提供总的概要，正文给出文档的中心内容，在必要时还应包含附录、参考资料等等。按照规范的说明，同一个项目的几个文档之间可能有些部分相同，如引言、各种文档中对功能性能的说明、对输入输出的描述以及对系统包含的设备介绍等说明部分，这种重复是必要的。为了方便每种文档各自的读者，每种文档应该自成体系，尽量避免读一种文档时又不得不去参考另外一种文档。

（7）可追溯性。由于各开发阶段编制的文档与各阶段完成的工作有着紧密的关系，前后两个阶段生成的文档，随着开发工作的逐步扩展，具有一定的继承关系。在一个项目各开发阶段之间提供文档必定存在着可追溯的关系。例如，某一项软件需求，必定在设计说明书、测试计划以至于用户手册中有所体现，必要时应能做到跟踪追查。

（8）灵活性。各个不同的软件项目，其规模和复杂程度因实际情况有着不同，所以不能一概而论，可以根据项目的大小对文档进行适当调整或合并。例如，对于较小和简单的项目，可以将用户手册和操作手册合并成用户操作手册；软件需求说明书中可包括对数据的要求，从而去掉数据要求说明书；概要设计说明书与详细设计说明书可以合并成软件设计说明书等。

由于产品如何使用在某种程度上要依赖技术文档来进行说明，因此技术文档必须十分准确可靠，而拥有准确的、高质量的技术文档不仅对于公司是十分有益的，而且能够让客户从中受益。而文档的编制则是一个需要不断努力工作的过程，从形成最初轮廓，经反复检查和修改，直到程序和文档正式交付使用。因此，项目小组在软件文档的编写过程中，为保证文档编制的质量，可以结合项目的特点，适当地采用下列文档编写技巧。

一、制订文档的编制计划

文档计划可以是整个项目计划中的一部分，也可以是一个独立的文档，而且文档的计划也应该遵循各项严格的标准及正规的评审和批准过程。

文档计划一般来说应该包含以下内容：

（1）列出应编制文档的目录，确定应该编制文档的种类以及详细程度。

（2）提示编制文档应参考的标准。

（3）提供编制文档所需要的条件，落实文档编写人员、所需经费以及编制工具等。

（4）明确保证文档质量的方法，为了确保文档内容的正确性、合理性，应采取的措施，如评审、鉴定等。

（5）绘制进度表，以图表的形式列出在软件生存期各阶段应产生的文档、编制人员、编制日期、完成日期、评审日期等。

（6）规定每个文档要达到的质量等级，以及为了达到期望的结果必须考虑哪些外部因素。

文档的编制计划在制订完成之后，要将其明确分发给全体开发组成员，作为文档重要性的具体依据和管理部门文档工作责任的备忘录。

二、从技术角度进行文档的编写和评价

软件文档是由软件技术人员编制完成的，其内容具有很强的技术性，而非一般的编辑工作。因此，编制和评价软件文档应从技术角度进行，专注于技术事实上，保证技术文档中编写的程序与步骤以及图片的准确性。

三、必须在技术文档编写的过程中明确责任

技术文档编写不好的一个原因常常在于对其不够重视，而这则是由于在编写技术文档过程中没有十分明确各种责任造成的。因此，在技术文档编写的过程中一定要明确责任。所以，应该在项目计划中指派专人负责技术评论的工作，并且在技术文档中加入作者以及相关人员的姓名。这样做不仅能够促进内部员工之间的交流，同时可以明确和承认他们对开发所做的工作和作出的贡献。

四、制定文档模板

文档模板是一种文档规范，它将文档按编制人员最常用的方法分类，然后对每类文档的形式和内容进行总结而形成的标准规范。文档模板，不仅使软件文档的形式和内容规范化，还便于相关人员进行高效准确的交流，同时使得软件开发人员的工作和软件项目的管理规范化。一些国际标准提供了文档模板，这些模板对软件开发组织具有通用性，往往比较烦琐。因此，企业可以以这些模板为基础，结合实际和企业经验来设计适合企业的标准文档模板。

五、软件文档的再利用

软件的开发过程中要产生大量的文档，但并不意味着每一个文档都要从无到有地分析、创建，软件开发组织可以充分利用已有软件文档的价值，借助一定的规范和方法，实现软件文档的再利用。根据不同的情况，软件文档的形式有部分借用、整体借用、完全重用三种。在确定标准的软件文档模板的基础上，软件文档的再利用比较容易实现。

六、使用文档自动化编制工具创建软件文档

软件文档贯穿于软件项目开发和维护的全过程，并且软件文档起着辅助设计和开发的作用，所以软件文档的编制不只是简单的文档制作，它应体现分析、设计、开发等不同阶段的不同软件模型。然而手工编写文档不但速度很慢，而且占用大量的人力资源和时间，因此，为了进一步提高文档编制的效率和质量，软件开发者可以使用基于模板的文档自动化编制工具。