如何编写高质量的软件技术文档

如何编写高质量的软件文档

摘要：

本文首先阐述了软件文档的重要性；接着描述了软件文档的分类和编写原则、技巧；最后针对我们在编写概要设计说明书中存在的不足，提出了一些指导性原则和大家分享。通过这次分享，希望对大家编写概设等文档时有所帮助。

正文：

我在面试的时候，发现好多公司面试官都不问我写代码的能力如何，JAVA的熟练程度如何，而问我口头和书面表达能力如何，写方案的能力如何，他还说，你写的代码可能只有你的团队或将来维护你程序的人来看；而高层领导，老板和客户他们只看文档的，不会看你的代码的（不是说代码不重要，保证程序运行的正确性和提高代码的运行效率是程序员最基本的能力和职责），刚开始觉着很奇怪，可仔细想想，确实是那样，像我们这种写了多年代码的程序员来说，除了写好代码，其实写得一手好文档尤其重要，文档写不好是程序员向上发展的瓶颈，要提升自己可以先从编写高质量的文档开始。

对于软件开发人员来说，除了保证程序运行的正确性和提高代码的运行效率之外，规范化的文档编制将会对软件的升级、修改、

维护带来极大的方便。因此，开发一个高质量的软件产品，除了完成软件程序本身编制外，还必须提供完整详细的软件文档。

在软件生命周期中，软件文档记载了所有与软件有关的需求、开发、方法等核心技术信息，是保证软件项目开发、运行、维护和管理的重要技术资料。

为了何证软件开发、维护等环节的有效管理以及方便软件技术人员之间进行技术交流，在软件生命周期的每一阶段，都需要编制不同内容的文档。这些文档连同计算机程序及数据一起，构成计算机软件。

软件文档也称做软件文件，是一种重要的软件工程技术资源，例如技术文档、设计文档。软件文档和计算机程序共同构成了能完成特定功能的计算机软件，因此可以说没有文档的软件，不能称其为软件，更不能成为软件产品。

软件文档的规范编制在软件开发工作中占有突出的地位和相当的工作量。高质量地编制、分发、管理和维护文档，及时地变更、修正、扩充和使用文档，对于充分发挥软件产品的效益有着十分重要的意义。

一、软件文档的重要性

软件文档作为计算机软件的重要组成部分，在软件开发人员、软件管理人员、软件维护人员、用户以及计算机之间起着重要的桥梁作用，软件开发人员通过软件文档交流设计思想和设计软件；软件管理人员通过文档了解软件开发项目安

排、进度、资源使用和成果等；软件维护人员通过文档对项目进行维护；用户通过文档掌握软件的使用和操作。软件文档在产品开发过程中具有重要的桥梁作用。

为了使软件文档能起到多种桥梁作用，使它有助于程序员编制程序，有助于管理人员监督和管理软件开发，有助于用户了解软件的工作和应做的操作，有助于维护人员进行有效的修改和扩充。文档的编制必须保证一定的质量。质量差的软件文档不仅使读者难以理解，给使用者造成许多不便，增加软件的成本，甚至造成更加有害的后果，如操作等。

造成软件文档质量不高的原因可能是：

①缺乏实践经验，缺乏评价文档质量的标准。

②不重视文档编写工作，或是对文档编写工作的按排不恰当。

最常见到的情况是，软件开发过程中不能及时完成文档的编制工作，而是在开发工作接近完成时集中精力和时间专门编写文档。另一方面，和程序工作相比，许多人对编制文档不感兴趣。于是在程序工作完成以后，不得不应付一下，把要求提供的文档赶写出来。这样的做法不可能得到高质量的文档。

（1）、项目管理的依据

软件文档向管理人员提供软件开发过程中的进展和情况，把软件开发过程中的一些“不可见的”事物转换成“可见的”

文字资料，以便管理人员在各个阶段检查开发计划的实施进展，使之能判断原定目标是否已达到，以及继续耗用资源的种类和数量。

（2）、技术交流的语言

大多数软件开发项目通常被划分成若干个任务，并由不同的小组去完成。专业技术领域方面的专家负责建立项目；分析员负责阐述系统需求；设计员负责为程序员制定总体设计；程序员负责编制详细的程序代码；质量保证专家和审查员负责评价整个系统性能和功能的完整性；负责维护的程序员负责改进各种操作或增强某些功能。这些技术人员之间的交流和联系正是通过文档来实现的，因此，软件文档可以看成是软件技术人员进行“技术交流的语言”。

（3）、保证项目质量

软件文档是进行项目质量审查和评价的重要依据，也是保证软件项目质量的重要技术文档。那些负责软件质量保证和评估系统性能的人员需要程序规格说明、测试和评估计划、测试该系统用的各种质量标准以关于期望系统完成什么功能和系统怎样实现这些功能的清晰说明。必须制定测试计划和测试规程，并报告测试结果；他们还必须说明和评估、控制、计算、检验例行程序及其他控制技术。这些文档的提供可满足质量保证人员和审查人员上述工作的需要。

（4）、培训与维护的资料

软件文档提供对软件的有关运行、维护和培训的信息，便于管理人员、开发人员、操作人员和用户了解系统如何工作，以及如何使用系统。

（5）、软件维护支持

维护人员需要软件系统的详细说明以帮助他们熟悉系统，找出并修正错误，改进系统以适应用户需求的变化或适应环境的变化。

（6）、记载软件历史的语言

软件文档作为“记载软件历史的语言”，记录了开发过程中的技术信息，便于协调以后的软件开发、使用和修改。软件文档可用作未来项目的一种资源，向潜在用户报导软件的功能和性能，使他们能判定该软件能否服务于自己的需要。

良好的系统文档有助于把程序移植和转移到各种新的系统环境中。

二、软件文档的分类

软件文档可以用自然语言，各类图形和表格等方法进行编制。文档可以书写编制，也可以利用计算机支持系统辅助编制，但必须方便阅读。

软件文档从形式上来看，大致可分为两类：一类是开发过程中填写的各种图表，称之为工作表格；一类是应编制的技术资料或技术管理资料，称之为文档或文件。

按照文档产生和使用的范围，软件文档可分为开发文档、