软件工程/工具/软件文档简介

软件文档 或 源代码文档 是伴随计算机软件的书面文字。它要么解释软件如何运行，要么解释如何使用它，并且对不同角色的人可能意味着不同的东西。

人员在软件生命周期中的参与

文档是软件工程的重要组成部分。文档类型包括

1. 需求 - 识别系统属性、功能、特性或质量的陈述。这是对将要实现或已实现内容的基础。
2. 架构/设计 - 软件概述。包括与环境的关系和用于软件组件设计的构建原则。
3. 技术 - 代码、算法、接口和 API 的文档。
4. 最终用户 - 为最终用户、系统管理员和支持人员准备的手册。
5. 市场营销 - 如何营销产品以及市场需求分析。

需求文档

需求文档是对特定软件执行或将要执行的功能的描述。它在整个开发过程中使用，用于传达软件的功能或将要执行的功能。它也用作协议或协议基础，说明软件将要执行的功能。需求由参与软件生产的每个人产生和使用：最终用户、客户、产品经理、项目经理、销售、市场营销、软件架构师、可用性工程师、交互设计师、开发人员和测试人员等等。因此，需求文档有许多不同的目的。

需求有多种风格、符号和形式。需求可以是目标式的（例如，分布式工作环境），接近设计的（例如，可以通过右键单击配置文件并选择“构建”功能来启动构建），以及介于两者之间的任何内容。它们可以指定为自然语言语句、绘制的图形、详细的数学公式以及它们的组合。

需求文档的多样性和复杂性使其成为一个公认的挑战。需求可能是隐性的，难以发现。很难确切地知道需要多少和哪种文档，以及可以留给架构和设计文档的内容，并且很难考虑到将要阅读和使用文档的各种人员，从而知道如何记录需求。因此，需求文档往往是不完整的（或不存在）。如果没有适当的需求文档，软件变更将变得更加困难，因此更易出错（降低软件质量）且耗时（成本高昂）。

对需求文档的需求通常与产品的复杂性、产品的影響以及软件的预期寿命有关。如果软件非常复杂或由多人开发（例如，移动电话软件），需求可以帮助更好地传达要实现的目标。如果软件是安全关键的，并且会对人身安全造成负面影响（例如，核电系统、医疗设备），通常需要更正式的需求文档。如果软件预期寿命只有一个月或两个月（例如，专门针对特定活动开发的非常小的移动电话应用程序），可能只需要很少的需求文档。如果软件是第一个版本，之后会在此基础上进行构建，则在管理软件变更和验证修改软件时未破坏任何内容时，需求文档非常有用。

传统上，需求在需求文档中指定（例如，使用文字处理应用程序和电子表格应用程序）。为了管理日益增长的需求文档复杂性和不断变化的性质（以及一般意义上的软件文档），人们提倡使用以数据库为中心的系统和专门的需求管理工具。

架构/设计文档

架构文档是一种特殊的设计文档。从某种意义上说，架构文档是从代码派生的第三个衍生物（设计文档是第二个衍生物，代码文档是第一个衍生物）。架构文档中很少有内容是针对代码本身的。这些文档不描述如何编写特定例程，甚至不描述为什么该特定例程以其形式存在，而是仅概述了将促使该例程存在的总体要求。好的架构文档简短描述细节，但解释详尽。它可能为更低级别的设计提出建议，但将实际的探索权衡研究留给其他文档。

另一种设计文档是比较文档或权衡研究。这通常以白皮书的形式出现。它专注于系统的某个特定方面，并提出替代方法。它可以处于用户界面、代码、设计甚至架构级别。它将概述当前情况，描述一种或多种替代方案，并列举每种方案的优缺点。好的权衡研究文档注重研究，清晰地表达其想法（不依赖于含糊的术语来炫耀读者），最重要的是保持公正。它应该诚实地清楚地解释它提供的任何解决方案的成本。权衡研究的目的是设计最佳解决方案，而不是推动特定观点。没有得出结论或得出结论，即没有哪种替代方案比基线足够好以至于需要更改，都是完全可以接受的。它应该被视为一项科学工作，而不是一种营销手段。

企业软件开发中设计文档非常重要的一个部分是数据库设计文档 (DDD)。它包含概念、逻辑和物理设计元素。DDD 包含与数据库交互的人员所需的形式信息。编制它的目的是创建一个可在场景中所有参与者之间使用的通用来源。潜在用户是

• 数据库设计师
• 数据库开发人员
• 数据库管理员
• 应用程序设计师
• 应用程序开发人员

在谈论关系型数据库系统时，文档应包括以下部分

• 实体 - 关系模式，包括以下信息及其明确定义
  • 实体集及其属性
  • 关系及其属性
  • 每个实体集的候选键
  • 基于属性和元组的约束
• 关系模式，包括以下信息
  • 表、属性及其属性
  • 视图
  • 约束，例如主键、外键
  • 引用约束的基数
  • 引用约束的级联策略
  • 主键

包含所有将要被场景中所有参与者使用信息非常重要。更新数据库发生任何更改时的文档也同样重要。

技术文档

这就是大多数程序员使用术语软件文档时的意思。在创建软件时，仅有代码是不够的。必须有一些文本与之一起，以描述其预期操作的各个方面。代码文档必须完整，但不能过于冗长，以至于难以维护它们。API 编写人员在为其所记录的软件应用程序或软件产品提供许多操作方法和概述文档。开发人员、测试人员以及使用该软件应用程序的最终客户或客户可能会使用此文档。如今，我们在电力、能源、交通运输、网络、航空航天、安全、安保、工业自动化以及各种其他领域看到了很多高端应用程序。技术文档在这些组织中变得越来越重要，因为随着架构的改变，基本和高级的信息可能会随着时间的推移而改变。因此，技术文档在近些年变得非常重要，特别是在软件领域。

通常，可以使用 Doxygen、NDoc、javadoc、EiffelStudio、Sandcastle、ROBODoc、POD、TwinText 或 Universal Report 等工具自动生成代码文档，即它们从源代码中提取注释和软件契约（如果存在），并创建以文本或 HTML 文件等形式的参考手册。代码文档通常组织成参考指南风格，使程序员可以快速查找任意函数或类。

自动生成文档的想法对程序员来说很有吸引力，原因有很多。例如，因为它是从源代码本身提取的（例如，通过注释），程序员可以在参考代码时编写它，并使用与创建源代码相同的工具来制作文档。这使得保持文档更新变得容易得多。

当然，一个缺点是只有程序员可以编辑这种文档，并且它依赖于他们来刷新输出（例如，通过运行 cron 作业来每晚更新文档）。有些人会将此归类为优点而不是缺点。

唐纳德·克努特坚持认为，文档可能是一个非常困难的后续过程，并且主张“文学编程”，即在与源代码相同的时间和位置编写文档，并通过自动方式提取。

阐释编程是文学编程在实际编程环境中的实际应用的结果。阐释范式提出将源代码和文档分别存储。该范式受产生 Kelp 的相同实验发现的启发。通常，软件开发人员需要能够创建和访问不会成为源文件本身一部分的信息。这些注释通常是几个软件开发活动的一部分，例如代码演练和移植，其中第三方源代码以功能的方式进行分析。因此，注释可以在软件开发的任何阶段帮助开发人员，在这些阶段，正式的文档系统会阻碍进度。 Kelp 将注释存储在单独的文件中，动态地将信息链接到源代码。

用户文档

与代码文档不同，用户文档通常在程序的源代码方面差异很大，而只是描述了如何使用它。

在软件库的情况下，代码文档和用户文档可能有效地等效，并且值得合并，但对于一般应用程序来说，这并不经常发生。

通常，用户文档描述了程序的每个功能，并帮助用户实现这些功能。好的用户文档还可以提供全面的故障排除帮助。用户文档不能混淆并且必须保持最新，这一点非常重要。用户文档不必以任何特定方式组织，但它们必须具有完整的索引，这一点非常重要。一致性和简单性也很有价值。用户文档被认为构成了指定软件将执行的操作的合同。API 编写者在编写好的用户文档方面非常出色，因为他们会非常了解软件体系结构和使用的编程技术。另请参阅技术写作。

用户文档可以组织的三种主要方式是：

1. 教程：教程方法被认为对新用户最有帮助，其中引导他们完成完成特定任务的每个步骤。
2. 主题：主题方法，其中章节或部分集中在某个特定感兴趣的领域，对中级用户来说更通用。有些作者更喜欢通过基于知识的文章来传达他们的想法，以促进用户需求。这种方法通常由动态行业（如信息技术）采用，在该行业中，用户群与故障排除需求高度相关^, 。
3. 列表或参考：组织原则的最后一种类型是简单地按字母顺序或逻辑分组列出命令或任务，通常通过交叉引用索引。后一种方法对高级用户更有用，他们确切地知道他们正在寻找什么样的信息。

用户对软件文档的常见抱怨是，只采用这三种方法中的一种，几乎排除了其他两种方法。通常，将为个人计算机提供的软件文档限制为在线帮助，该帮助仅提供有关命令或菜单项的参考信息。辅导新用户或帮助更有经验的用户充分利用程序的任务留给了私人出版商，这些出版商通常会从软件开发人员那里获得大量帮助。

营销文档

对于许多应用程序，必须提供一些宣传材料来鼓励临时观察者花更多时间了解产品。这种形式的文档有三个目的：

1. 激发潜在用户对产品的兴趣，并激发他们对参与该产品的愿望。
2. 告知他们产品的确切功能，以便他们的期望与他们将获得的功能一致。
3. 解释该产品相对于其他替代方案的定位。

一种好的营销技巧是提供清晰且令人难忘的口号，以体现我们希望传达的观点，并强调该程序与制造商提供的任何其他内容的互操作性。

外部链接

• kelp - 用于架构、设计和技术文档的源代码注释框架。
• ISO 文档标准委员会 - 制定用户文档标准的国际标准化组织委员会。