软件文档类型和最佳实践

软件工程中的文档（Documentation）是一个总称，涵盖了所有涉及软件产品开发和使用的书面文档和材料。所有软件开发产品，无论是由小团队还是大公司创建，都需要一些相关文档。在整个软件开发生命周期 （SDLC） 中创建不同类型的文档。文档的存在是为了解释产品功能，统一与项目相关的信息，并允许讨论与记录利益相关者和开发人员之间出现的所有重大问题。

最重要的是，文档错误可能会在利益相关者和工程师的愿景之间产生差距，因此，拟议的解决方案将无法满足利益相关者的期望。因此，管理者应该非常注意文档质量。

团队生成的文档类型及其范围取决于所选择的软件开发方法。主要有两个：敏捷和瀑布。每个在随附文档方面都是独一无二的。

敏捷方法基于团队合作、与客户和利益相关者的密切合作、灵活性以及快速响应变化的能力。敏捷开发的基本构建块是迭代;它们中的每一个都包括规划、分析、设计、开发和测试。敏捷方法在开始时不需要全面的文档。经理不需要提前做太多计划，因为事情会随着项目的发展而变化。这允许及时规划。正如敏捷宣言的价值观之一所建议的那样，将“工作软件置于全面的文档之上”，其想法是生成包含对前进至关重要的信息的文档，当它最有意义时。

今天，敏捷是软件开发中最常见的实践，因此我们将重点关注与此方法相关的文档实践。

有效文档的主要目标是确保开发人员和利益相关者朝着同一个方向前进，以实现项目的目标。为了实现它们，存在许多文档类型。

遵守以下分类。

所有软件文档可分为两大类：

• 产品文档

• 流程文档

产品文档描述了正在开发的产品，并提供了有关如何使用它执行各种任务的说明。产品文档可分为：

• 系统文档

• 用户文档

系统文档表示描述系统本身及其部件的文档。它包括需求文档、设计决策、体系结构描述、程序源代码和帮助指南。

用户文档涵盖主要为产品的最终用户和系统管理员准备的手册。用户文档包括教程、用户指南、故障排除手册、安装和参考手册。

流程文档表示在开发和维护过程中生成的所有文档，这些文档描述了…好吧，流程。流程文档的常见示例包括项目计划、测试计划、报告、标准、会议记录，甚至是商业信函。

流程文档和产品文档之间的主要区别在于，第一个文档记录开发过程，第二个文档描述正在开发的产品。

产品：系统文档

系统文档提供了系统的概述，并帮助工程师和利益相关者了解底层技术。它通常由需求文档、体系结构设计、源代码、验证文档、验证和测试信息以及维护或帮助指南组成。值得强调的是，此列表并非详尽无遗。那么，让我们看一下主要类型的详细信息。

需求文档

需求文档提供有关系统功能的信息。通常，需求是系统应该做什么的陈述。它包含业务规则、用户故事、用例等。这份文件应该清晰明了，不应该是一堵广泛而坚实的文字墙。它应该包含足够的内容来概述产品的用途、特性、功能和行为。最佳做法是使用所有团队成员都遵守的单一、一致的模板编写需求文档

以下是撰写需求文档要遵循的主要建议：

1. 角色和职责。在文档的开头包含有关项目参与者的信息，包括产品所有者、团队成员和利益干系人。这些细节将明确职责并传达每个团队成员的目标发布目标。

2. 团队目标和业务目标。以简短的点形式定义最重要的目标。

3. 背景和战略契合度。简要说明您的行动的战略目标。为什么要构建产品？您的行为如何影响产品开发并与公司目标保持一致？

4. 假设。创建团队可能具有的技术或业务假设列表。

5. 用户故事。列出或链接项目所需的用户情景。用户故事是从使用您的软件产品的人的角度编写的文档。用户故事是对客户想要实现的行动和结果的简短描述。

6. 用户交互和设计。将设计探索和线框链接到页面。

7. 问题。当团队在项目进展过程中解决问题时，他们不可避免地会出现许多问题。一个好的做法是记录所有这些问题并跟踪它们。

8. 待办事项。列出你现在没有做但计划很快做的事情。这样的列表将帮助您组织团队合作并确定功能的优先级。

使用以下做法使所有这些信息更加全面：

• 使用链接和锚点。它们将帮助您使文档更易于阅读和搜索，因为读者将能够逐渐理解信息。例如，您可以提供指向客户访谈的链接和指向先前讨论或与项目相关的其他外部信息的锚点。

• 使用图表工具更好地将问题传达给您的团队。人们更有可能通过查看图像来感知信息，而不是阅读大量文档。不同的可视化模型将帮助您更有效地执行此任务并概述需求。您可以使用以下软件图表工具将图表合并到需求流程中：Visio，Gliffy，Balsamiq，Axure或Microsoft Office中的SmartArt。

软件架构文档

软件架构设计文档包括主要的架构决策。我们不建议列出所有内容，而是专注于最相关和最具挑战性的。有效的设计和架构文档包括以下信息部分：

• 设计文档模板。在创建架构设计文档之前，与利益相关者讨论并就架构设计文档中需要涵盖的内容达成共识，并使用定义的模板来映射架构解决方案。

• 架构与设计原则。强调您将用于设计产品的指导架构和设计原则。例如，如果您计划使用微服务体系结构构建解决方案，请不要忘记特别提及这一点。

• 用户故事描述。将用户情景与关联的业务流程和相关方案联系起来。您应尽量避免本节中的技术细节。

• 解决方案详细信息。通过列出计划中的服务、模块、组件及其重要性来描述预期的解决方案。

• 解决方案的图示。确定需要创建的图表，以帮助理解和传达结构和设计原则。

源代码文档

源代码文档是解释代码工作原理的技术部分。虽然没有必要，但应该涵盖最有可能混淆的方面。源代码文档的主要用户是软件工程师。

源代码文档可能包括但不限于以下详细信息：

• HTML生成框架和其他应用的框架

• 数据绑定的类型

• 带有示例的设计模式（例如模型-视图-控制器）

• 安全措施

• 其他模式和原则

尝试通过为每个元素制作简短的部分并用简短的描述来支持它们来保持文档的简单性。

质量保证文件

敏捷中有不同类型的测试文档。我们概述了最常见的：

• 测试策略

• 测试计划

• 测试用例规范

• 测试清单

测试策略是描述实现测试目标的软件测试方法的文档。本文档包含有关团队结构和资源需求的信息，以及测试期间应优先考虑的事项。测试策略通常是静态的，因为该策略是针对整个开发范围定义的。

测试计划通常由一页或两页组成，描述了在给定时刻应该测试的内容。本文件应包含：

• 要测试的功能列表

• 测试方法

• 时间框架

• 角色和职责（例如，单元测试可以由QA团队或工程师执行）

测试用例规范文档是一组详细操作，用于验证产品的每个特性或功能。通常，QA 团队为每个产品单元编写单独的规格文档。测试用例规范基于测试计划中概述的方法。一个好的做法是简化规范描述并避免重复测试用例。

测试清单是在特定时间应运行的测试列表。它表示哪些测试已完成，有多少测试失败。测试清单中的所有点都应正确定义。尝试在清单中对测试点进行分组。这种方法将帮助您在工作期间跟踪它们，而不会丢失任何内容。如果它有助于测试人员正确检查应用程序，您可以向列表中的点添加注释。

本文档应描述系统的已知问题及其解决方案。它还应该表示系统不同部分之间的依赖关系。

产品：用户文档

顾名思义，用户文档是为产品用户创建的。但是，它们的类别也可能有所不同。因此，您应该根据不同的用户任务和不同的体验水平来构建用户文档。通常，用户文档针对两大类：

• 终端用户

• 系统管理员

为最终用户创建的文档应以尽可能短的方式解释软件如何帮助解决他们的问题。在许多基于客户的大型产品中，用户文档的某些部分（如教程和入门）被入门培训所取代。尽管如此，仍有复杂的系统需要记录在案的用户指南。

用户文档的在线形式要求技术撰写人更具想象力。联机最终用户文档应包括以下部分：

• 常见问题

• 视频教程

• 嵌入式辅助

• 支持门户

为了给最终用户提供最好的服务，您应该不断收集客户反馈。wiki 系统是比较有用的实践之一。它有助于维护现有文档。如果您使用 wiki 系统，则无需将文档导出为可呈现的格式并将它们上传到服务器。您可以使用 Wiki 标记语言和 HTML 代码创建 Wiki 页面。

系统管理员的文档不需要提供有关如何操作软件的信息。通常，管理文档涵盖帮助系统管理员进行产品维护的安装和更新。以下是标准的系统管理员文档：

• 功能描述 — 描述产品的功能。本文档的大部分内容是在与用户或所有者协商后制作的。

• 系统管理员指南 — 解释系统在不同环境和其他系统中的不同类型的行为。它还应该提供如何处理故障情况的说明。

流程文档

流程文档涵盖与产品开发相关的所有活动。保留流程文档的价值在于使开发更有条理和计划性。这个文档分支在项目开始之前和开发期间都需要一些规划和文书工作。以下是常见的流程文档类型：

• 计划、估算和时间表。这些文档通常是在项目开始之前创建的，并且可以随着产品的发展而更改。

• 报告和指标。报告反映了在开发过程中如何利用时间和人力资源。它们可以每天、每周或每月生成。请参阅我们关于敏捷交付指标的文章，了解有关流程文档的更多信息，例如速度聊天、冲刺燃尽图和发布燃尽图。

• 工作文件。这些文件的存在是为了记录工程师在项目实施过程中的想法和想法。工作论文通常包含有关工程师代码、草图和如何解决技术问题的想法的一些信息。虽然它们不应该是主要的信息来源，但跟踪它们可以在需要时检索高度具体的项目详细信息。

• 标准。标准部分应包括团队在项目过程中遵守的所有编码和 UX 标准。

大多数流程文档都特定于流程的特定时刻或阶段。结果是这些文件很快就会过时和过时。但它们仍然应该作为开发的一部分保留，因为它们可能会在将来实现类似的任务或维护时变得有用。此外，流程文档有助于使整个开发更加透明和易于管理。

过程文档的主要目标是减少系统文档的数量。为了实现这一点，请编写最小的文档计划。列出关键联系人、发布日期和您的期望以及假设。

有几种常见的做法应该应用于我们上面讨论的所有类型的文档：

编写足够的文档

您应该在无文档和过多文档之间找到平衡。糟糕的文档会导致许多错误，并降低软件产品开发每个阶段的效率。同时，没有必要在几篇论文中提供大量的文件和重复信息。只应记录最必要和最相关的信息。找到合适的平衡点还需要在开发开始之前分析项目的复杂性。

文档是一个持续的过程

这意味着您应该使文档保持最新。这非常重要，因为不是最新的文档会自动失去其价值。如果在软件开发过程中需求发生变化，则需要确保有一个系统的文档更新过程，其中包含已更改的信息。您可以使用自动版本控制来更有效地管理此过程。

文档是所有团队成员的协作成果

敏捷方法基于创建文档的协作方法。如果您想提高效率，请就软件的功能采访程序员和测试人员。然后，在编写一些文档后，与您的团队共享并获得反馈。要获得更多信息，请尝试发表评论、提出问题并鼓励其他人分享他们的想法和想法。每个团队成员都可以为您制作的文档做出宝贵的贡献。

聘请技术作家

如果可以的话，值得雇用一名员工来处理您的文件。通常从事这项工作的人称为技术作家。具有工程背景的技术作家可以从开发人员那里收集信息，而无需某人详细解释正在发生的事情。还值得将技术作家嵌入为团队成员，将此人放在同一个办公室以建立密切合作。他或她将能够参加定期会议和讨论。

一锤定音

敏捷方法鼓励工程团队始终专注于为客户提供价值。在制作软件文档的过程中也必须考虑这一关键原则。无论是程序员和测试人员的规范文档，还是最终用户的软件手册，都应提供良好的软件文档。全面的软件文档是具体、简洁和相关的。

最后，正如我们上面提到的，没有必要提供本文中描述的整套文档。您应该只关注那些直接有助于实现项目目标的文档。

关注公众号妙坊咨询，视频号白胡子研究所，学习更多项目管理干货。