如何编写高质量的软件文档
摘要：
本文首先阐述了软件文档的重要性；接着描述了软件文档的分类和编写原则、技巧；最后针对我们在编写概要设计说明书中存在的不足，提出了一些指导性原则和大家分享。通过这次分享，希望对大家编写概设等文档时有所帮助。
正文：
我在面试的时候，发现好多公司面试官都不问我写代码的能力如何，JAVA的熟练程度如何，而问我口头和书面表达能力如何，写方案的能力如何，他还说，你写的代码可能只有你的团队或将来维护你程序的人来看；而高层领导，老板和客户他们只看文档的，不会看你的代码的（不是说代码不重要，保证程序运行的正确性和提高代码的运行效率是程序员最基本的能力和职责），刚开始觉着很奇怪，可仔细想想，确实是那样，像我们这种写了多年代码的程序员来说，除了写好代码，其实写得一手好文档尤其重要，文档写不好是程序员向上发展的瓶颈，要提升自己可以先从编写高质量的文档开始。
对于软件开发人员来说，除了保证程序运行的正确性和提高代码的运行效率之外，规范化的文档编制将会对软件的升级、修改、维护带来极大的方便。因此，开发一个高质量的软件产品，除了完成软件程序本身编制外，还必须提供完整详细的软件文档。
在软件生命周期中，软件文档记载了所有与软件有关的需求、开发、方法等核心技术信息，是保证软件项目开发、运行、维护和管理的重要技术资料。
为了何证软件开发、维护等环节的有效管理以及方便软件技术人员之间进行技术交流，在软件生命周期的每一阶段，都需要编制不同内容的文档。这些文档连同计算机程序及数据一起，构成计算机软件。
软件文档也称做软件文件，是一种重要的软件工程技术资源，例如技术文档、设计文档。软件文档和计算机程序共同构成了能完成特定功能的计算机软件，因此可以说没有文档的软件，不能称其为软件，更不能成为软件产品。
软件文档的规范编制在软件开发工作中占有突出的地位和相当的工作量。高质量地编制、分发、管理和维护文档，及时地变更、修正、扩充和使用文档，对于充分发挥软件产品的效益有着十分重要的意义。
一、 软件文档的重要性
软件文档作为计算机软件的重要组成部分，在软件开发人员、软件管理人员、软件维护人员、用户以及计算机之间起着重要的桥梁作用，软件开发人员通过软件文档交流设计思想和设计软件；软件管理人员通过文档了解软件开发项目安排、进度、资源使用和成果等；软件维护人员通过文档对项目进行维护；用户通过文档掌握软件的使用和操作。软件文档在产品开发过程中具有重要的桥梁作用。
为了使软件文档能起到多种桥梁作用，使它有助于程序员编制程序，有助于管理人员监督和管理软件开发，有助于用户了解软件的工作和应做的操作，有助于维护人员进行有效的修改和扩充。文档的编制必须保证一定的质量。质量差的软件文档不仅使读者难以理解，给使用者造成许多不便，增加软件的成本，甚至造成更加有害的后果，如操作等。
造成软件文档质量不高的原因可能是：
①缺乏实践经验，缺乏评价文档质量的标准。
②不重视文档编写工作，或是对文档编写工作的按排不恰当。
最常见到的情况是，软件开发过程中不能及时完成文档的编制工作，而是在开发工作接近完成时集中精力和时间专门编写文档。另一方面，和程序工作相比，许多人对编制文档不感兴趣。于是在程序工作完成以后，不得不应付一下，把要求提供的文档赶写出来。这样的做法不可能得到高质量的文档。
（1）、项目管理的依据
软件文档向管理人员提供软件开发过程中的进展和情况，把软件开发过程中的一些“不可见的”事物转换成“可见的”文字资料，以便管理人员在各个阶段检查开发计划的实施进展，使之能判断原定目标是否已达到，以及继续耗用资源的种类和数量。
（2）、技术交流的语言
大多数软件开发项目通常被划分成若干个任务，并由不同的小组去完成。专业技术领域方面的专家负责建立项目；分析员负责阐述系统需求；设计员负责为程序员制定总体设计；程序员负责编制详细的程序代码；质量保证专家和审查员负责评价整个系统性能和功能的完整性；负责维护的程序员负责改进各种操作或增强某些功能。这些技术人员之间的交流和联系正是通过文档来实现的，因此，软件文档可以看成是软件技术人员进行“技术交流的语言”。
（3）、保证项目质量
软件文档是进行项目质量审查和评价的重要依据，也是保证软件项目质量的重要技术文档。那些负责软件质量保证和评估系统性能的人员需要程序规格说明、测试和评估计划、测试该系统用的各种质量标准以关于期望系统完成什么功能和系统怎样实现这些功能的清晰说明。必须制定测试计划和测试规程，并报告测试结果；他们还必须说明和评估、控制、计算、检验例行程序及其他控制技术。这些文档的提供可满足质量保证人员和审查人员上述工作的需要。
（4）、培训与维护的资料
软件文档提供对软件的有关运行、维护和培训的信息，便于管理人员、开发人员、操作人员和用户了解系统如何工作，以及如何使用系统。
（5）、软件维护支持
维护人员需要软件系统的详细说明以帮助他们熟悉系统，找出并修正错误，改进系统以适应用户需求的变化或适应环境的变化。
（6）、记载软件历史的语言
软件文档作为“记载软件历史的语言”，记录了开发过程中的技术信息，便于协调以后的软件开发、使用和修改。软件文档可用作未来项目的一种资源，向潜在用户报导软件的功能和性能，使他们能判定该软件能否服务于自己的需要。良好的系统文档有助于把程序移植和转移到各种新的系统环境中。
二、 软件文档的分类
软件文档可以用自然语言，各类图形和表格等方法进行编制。文档可以书写编制，也可以利用计算机支持系统辅助编制，但必须方便阅读。
软件文档从形式上来看，大致可分为两类：一类是开发过程中填写的各种图表，称之为工作表格；一类是应编制的技术资料或技术管理资料，称之为文档或文件。
按照文档产生和使用的范围，软件文档可分为开发文档、用户文档、管理文档3类。
|
软 件 文 档 |
文档类型 |
文档名称 |
|
用 户 文 档 |
用户手册 |
|
|
操作手册 |
||
|
软件需求说明书 |
||
|
数据要求说明书 |
||
|
开 发 文 档 |
可行性研究报告 |
|
|
项目开发计划 |
||
|
软件需求说明书 |
||
|
数据库设计说明书 |
||
|
概要设计说明书 |
||
|
详细设计说明书 |
||
|
管 理 文 档 |
项目开发计划 |
|
|
模块开发卷宗 |
||
|
开发进度月报 |
||
|
测试计划 |
||
|
测试分析报告 |
||
|
项目开发总结报告 |
（1）、开发文档
开发文档主要有以下5方面的作用：
① 它们是软件开发过程中各个阶段之间的通信工具，它们记录生成软件需求、设计、编码和测试的详细规定和说明。
② 它们描述开发小组的职责。通过规定软件、主题事项、文档编制、质量保证人员，以及包含在开发过程中任何其他事项的角色来定义“如何做”和“何时做”。
③ 它们用作检验点而允许管理者评定开发进度。如果开发文档丢失、不完整或过时，管理者将失去跟踪和控制软件项目的一个重要工具。
④它们形成了维护人员所要求的基本的软件支持文档。而这些支持文档可作为产品文档的一部分。
⑤它们记录软件开发的历史。
（2）、用户文档
用户文档主要有以下作用：
①为使用和运行软件产品的客户提供培训和参考信息；
②为那些未参加开发本软件的程序员维护它提供信息；
③促进软件产品的市场流通或提高可接受性。
用户文档适用于下列类型的读者。
用户：他们利用软件输入数据、检索信息和解决问题。
运行者：他们在计算机系统上运行软件。
维护人员：他们维护、增强或变更软件。
用户文档包括如下内容。
用于管理者的指南和资料。
宣传资料：通告软件产品的可用性并详细说明它的功能、运行环境等。
一般信息：对任何有兴趣的人描述软件产品。
（3）、管理文档
管理文档主要有以下作用：
①开发过程中每个阶段的进度和进度变更的记录
②软件变更情况的记录
③相对于发的判定记录
④职责定义
三、 软件文档的编写原则和技巧
原则：
文档编制是一个需要不断努力的工作过程。从形成最初轮廓，经反复检查和修改，直到文档正式交付使用，其中每一步都要求文档编写人员既要保证文档编制的质量，又要体现每个开发项目的特点。
（1）、应适应文档的读者
每一中文档都具有特定的读者。这些读者包括个人或小组、软件开发单位的成员或社会上的公众、从事软件工作的技术人员、管理人员或领导干部。他们期待着通过使用这些文档的内容来进行工作，如设计、编写程序、测试、使用、维护或进行计划管理。因此，这些文档的作者必须了解自己的读者，文档的编写必须注意适应自己的特定读者的水平、特点和要求，要站在读者的视角考虑问题。
（2）、完整性（应有必要的重复性）
为了方便每种文档各自的读者，每种产品文档应该自成体系，尽量避免阅读一种文档时又不得不去参考另一种文档，如阅读概要设计说明书时，要去找产品策划文档，这样读者就不方便，可以在概设的需求规定和功能描述的中说明。
（3）、精确性
文档的行文应当十分确切，不能出现多义性的描述。同一技术或功能若干文档内容应该协调一致，应是没矛盾的。
（4）、清晰性
文档编写应力求简明，必须配合适当的图表，以增强其清晰性。
（5）可追溯性
由于各开发阶段编制的文档与各阶段完成的工作有着紧密的关系，前后两个阶段生成的文档，随着开发工作的逐步扩展，具有一定的继承关系。在一个项目各开发阶段之间提供的文档必定存着可追溯的关系。如某一项软件需求，必定在设计说明书、测试计划以至用户手册中有所体现，必要时应能做到跟踪追查。
技巧：
（1）、从技术角度进行文档的编写和评价
软件文档是重要的技术资料，是由软件技术人员完成编制的，也就是说，文档编制工作并不等同于一般的文字编辑工作，软件文档的内容具有很强的技术性。因此，编制和评价软件文档应从技术角度进行，把注意力集中于技术事实上，保证文档中编写步骤以及使用图表的准确性，这样才能编写好的软件文档。
（2）、明确文档编写人员的责任
软件文档编写不好的一个原因是由于对它不够重视，这是由于在编写软件文档时，没有明确各种责任。因此，一定要在软件文档编写的过程中明确责任。
在文档中加入作者以及相关人员姓名是明确责任的一种好办法。在文档中包含文档编写人员以及相关人员的姓名不仅能明确责任，还能够促进这些人员之间的交流，同时可以明确承认他们对开发所做的工作和贡献。
（3）、编写人员必须对开发项目或功能有准确的认识
文档编写人员承担编写技术文档的职责，因此文档编写人员对编写对象了解的准确性直接影响技术文档编写的准确性。文档编写人员要多参加有关产品设计与开发的小组会议；更多地了解有关产品背后所包含的各种技术。
四、 概要设计说明书编写指南
我们目前写得最多的就是概要设计说明书了，这也适合我们公司项目的情况，因为有了概要设计完全可以进入编码和单元测试阶段了，详细设计一般由开发工程师来做，绝大部分公司一般都不会做详细设计，这也是受项目的进度约束，将详细设计留给开发工程师来做，有利于提升个人能力和工作的积极性也是必须的，因此用专门的章节来说说编写概设的一些想法和具体要求。
(1)、写作内容
目前我们在概要设计说明书里写什么不是很清楚，结合文档模板和面向对象分析和设计技术，说说针对某个模块或功能写什么。
|
模块/功能名称（短信双通道） |
写什么 |
|
需求描述 |
主要描述此模块功能所对应的需求，例如用户在发短信页面发送短信时，可以通过复选 框选择是否同时发送邮件到对方，如果选择复选框，该状态必须保存在数据表中，以记录用户选择行为，下次用户打开发短信页面时，程序自动显示上次选择的状态。列出对应产品策划案的文件名称和所在章节。 |
|
约束条件 |
主要描述该模块功能的限制和约束条件。例如最多支持50个手机号和50个邮箱号码的发送;必须是139邮箱的注册用户;同时接入内容和标题关键字过滤接口等等。 |
|
输入 |
主要描述短信双通道的输入项。例如接收人、接收标题、接收内容、是否发送邮件等。 |
|
输出 |
主要描述短信双通道的输出项，包括正确流程输出与异常流程输出。例如提示用户您的短信发送成功。异常为：您的短信发送失败，请稍后再试等等页面提示语。 |
|
关联的数据表 |
主要描述所用到的数据表名，例如短信发送表、用户配置表写上英文的表名，说明这个是否为公共库的等等。 |
|
逻辑设计 |
双通道的基本设计思路和处理流程，尽量使用图和表的形式来表现。图包括时序图、流程图、交互图、数据流图等方式。 对于增量的需求实现，处理流程要按功能点来，一个功能点对应一个处理流程，不能用一个笼统的架构图带过； 这里我建议用三个图来描述短信双通道的逻辑： 1、 类图，描述静态结构。 2、 活动图（流程图），描述动态行为。 3、 序列图，描述动态行为。 |
|
接口设计（用户接口） |
人机界面，例如发短信的页面，将UI原型拷贝过来，文档阅读人员一目了然就知道此功能是什么样子，不必找到产品策划案来看，也满足必要的重复要求。 |
|
接口设计（内部接口） |
类与类之间方法调用，例如可以将我们以前COPY的代码，写在这里，只需要写出类名和方法名，以及方法的功能及参数说明，这里的方法其实就是接口，不需要代码实现，因为实现已经在逻辑设计章节有说明。 |
|
接口设计（外部接口） |
外部第三方系统调用的接口中，我们一般将这类接口以http+xml的方式提供，建议将该功能封装成web service，这样可以复用。不必外部接口写一套，内部使用又要重复开发。 |
(2)、编写原则（需要补充在概要设计评审表中）
①目录下面的修改历史记录一定要填写，我们一般都是增量编写，这样文档读者一看就知道增加了什么，只看增加的内容即可，同时也记录了作者的功劳和责任。
②根据面向对象分析和设计要求，类图是描述系统的静态行为，需要写出类图和类与类之间的关系（泛化、实现、依赖、关联）。
③根据面向对象分析和设计的要求，活动图和序列图是描述系统的动态行为，说明对象与对象之间的调用关系。如果活动图中参与的对象有二个或以上时，必须使用泳道，描述各个对象不同的职责，活动由哪个对象来完成。
④在文档中，不需要程序代码，可以在接口设计中描述类与类之间的集成关系，写清方法的功能及参数约束即可，不需要有实现，实现在逻辑设计一章中用活动图和序列图已经说清楚了。
⑤图与图之间的连线，不要交叉，活动图中可以有多个终点，提高图表的可读性。
⑥对一个图的描述，注释数量不要大于2个，如果需要太多的注释才能将问题说清楚的话，证明这个图还可以细化。
(3)、评审检查表
谢谢!
