软件开发文档应该如何写？

如果我们知道软件文档的价值，那么为什么不经常使用它呢？对于新手，大多数软件文档都存在很多下面提到的这些问题：

· 糟糕的语法和/或拼写错误的词语

· 不完整

· 过期或不准确

· 篇幅太长

http://www.mscto.com

· 首字母缩写没有解释或术语不专业

http://www.mscto.com

· 难于找到信息或在文档中定位 软件开发网

存在这些问题的主要原因是软件文档通常没有被给予足够的重视。项目预算被迫将主要活动花在了开发工作上，在那里管理层很容易看到他们的收益。值得投入成本的文档工作通常都是主观的，而且通常被刻画为需要避免的成本，因为它们被认为不能产生投资回报（ROI）。很多项目经理将客户所需要的最少文档看作是“镀金”。

软件开发网

软件文档的另外一个麻烦来源是文档的作者。很多应用程序开发经理觉得软件文档是开发工作的一个标准部分，因此，要求他们的开发人员在编码时也编写软件文档。

虽然这在理论上是说得过去的，但是不应该将开发人员看成文档作者。很简单，技术人员只被培训如何开发，而没有被培训如何写文档。为了解决这一问题，很多应用程序开发经理尝试通过聘请一些技术性写手或商业分析人员来提高他们的软件文档的质量。这就导致出现了一个相反的问题：技术写手和商业分析人员通常只有有限的技术技能。

解决方案依赖于文档，文档应该迎合其潜在读者的口味。这方面的通用规则是要求使用一个协同工作方法来编写文档，这种方法允许开发人员和写手发挥他们的长处。例如，如果潜在的读者是系统设计人员，那么开发人员应该提供详细的输入，但是允许技术写手去组织和编辑内容以使文档符合语法。

不管潜在的读者还是被选中的读者，软件文档的质量与其可使用性相关，以下六个属性可以用来测量软件文档的可使用性：

· 适用性：文档提供了相关的信息吗？

· 合时性：文档所提供的是当时的信息吗？

· 正确性：文档所提供的信息正确吗？

· 完整性：文档是不是足够详细？

· 可用性：文档随手可用吗？

· 可使用性：能够快速直观地找

希望能助你一臂之力

模块开发卷宗（GB8567——88）
1标题
软件系统名称和标识符
模块名称和标识符（如果本卷宗包含多于一个的模块，则用这组模块的功能标识代替模块名）
程序编制员签名
卷宗的修改文本序号
修改完成日期
卷宗序号（说明本卷宗在整个卷宗中的序号）
编排日期（说明整个卷宗最近的一次编排日期）
2模块开发情况表
3功能说明
扼要说明本模块（或本组模块）的功能，主要是输入、要求的处理、输出。可以从系统设计说明书中摘录。同时列出在软件需求说明书中对这些功能的说明的章、条、款。
4设计说明
说明本模块（或本组模块）的设计考虑，包括：
a． 在系统设计说明书中有关对本模块（或本组模块）设计考虑的叙述，包括本模块在软件系统中所处的层次，它同其他模块的接口；
b． 在程序设计说明书中有关对本模块（或本组模块）的设计考虑，包括本模块的算法、处理流程、牵涉到的数据文卷设计限制、驱动方式和出错信息等；
c． 在编制目前已通过全部测试的源代码时实际使用的设计考虑。
5原代码清单
要给出所产生的本模块（或本组模块）的第一份无语法错的源代码清单以及已通过全部测试的当前有效的源代码清单。
6测试说明
说明直接要经过本模块（或本组模块）的每一项测试，包括这些测试各自的标识符和编号、进行这些测试的目的、所用的配置和输入、预期的输出及实际的输出。
7复审的结论
把实际测试的结果，同软件需求说明书、系统设计说明书、程序设计说明书中规定的要求进行比较和给出结论。