软件工程/实现/文档简介

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

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

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

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 文档标准委员会 - 制定用户文档标准的国际标准化组织委员会。