软件开发中的技术文档：类型、最佳实践和工具

本文中，我们将深入研究技术文档在软件开发中所扮演的关键角色。我们将指导您完成各种类型的文档，分享制作清晰简明文档的最佳实践，并介绍可以简化该过程的工具。

什么是软件开发中的技术文档?

软件工程中的技术文档是包含所有与软件产品开发相关的书面文档和材料的总称。所有的软件解决方案，无论是由小团队还是大公司创建的，在整个软件开发生命周期(SDLC)中都需要各种类型的文档。

project documentation at different stages of the SDLC

SDLC不同阶段的项目文档

技术文档解释了产品功能，帮助设计项目活动，并明确了最终目标。

有些人认为技术文档只是为开发团队创建的，但这并不完全正确。虽然它确实包含了大量的技术信息，但它实际上可以帮助不同的涉众小组达成一致，并共享对预期结果的共同理解。此外，正如我们将进一步解释的那样，不同类型的文档是为不同的受众创建的——有时，不是技术专家(例如，最终用户指南)。

软件文档的敏捷和瀑布方法

团队生成的文档类型及其范围取决于所选择的软件开发方法。主要有两种:敏捷和瀑布。就附带的技术文档而言，每个都是唯一的。

瀑布式方法

瀑布式方法是一种线性方法，在这种方法中，你只有在完成前一个阶段后才能进入下一个阶段。在项目的早期阶段，使用瀑布法的团队在产品规划上花费了相当多的时间。它们创建了主要目标和目的的广泛概述，并详细计划了工作过程的外观。

瀑布方法阶段

瀑布团队努力在任何工程阶段开始之前编写详细的文档。仔细的计划对于进度几乎没有变化的项目非常有效，因为它允许精确的预算和时间估计。然而，瀑布计划对于长期开发是无效的，因为它没有考虑到可能发生的变化和突发事件。

敏捷式方法

敏捷式方法基于团队合作、开发人员、业务涉众和最终客户之间的密切协作、灵活性和快速响应更改的能力。敏捷开发的基本构建模块是迭代:每个迭代都包括计划、设计、开发等阶段。

敏捷开发周期

敏捷方法在开始时不需要全面的文档。经理不需要提前计划太多，因为随着项目的发展，事情会发生变化。这允许进行及时的计划。

敏捷宣言的价值之一是“工作软件胜过全面的文档”。虽然敏捷更关注产品本身，但形式也不应该被忽视。因此，我们的想法是生成包含信息的文档，这些信息对于在最有意义的时候向前推进至关重要。

今天，敏捷是软件开发中最常见的实践:根据第17次敏捷状态报告，71%的公司在他们的SDLC中使用它。因此，我们将重点关注与此方法相关的文档实践。

技术文档的类型

有效文档的主要目标是确保开发人员和其他涉众一起工作来完成项目的目标。存在不同的软件文档类型来实现这一目标。

敏捷项目中最常用的软件文档

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

产品文档
流程文档

产品文档描述了正在开发的解决方案，并提供了如何与之交互的说明。一般来说，产品文档包括需求、技术规范、业务逻辑和手册。产品文档主要有两种类型:

系统文档描述系统本身及其组成部分。它包括需求文档、设计决策、体系结构描述、程序源代码等。
用户文档包括主要为产品最终用户和系统管理员准备的手册。它包括教程、用户指南、故障排除手册、安装说明等。

过程文档描述了团队在开发软件时如何工作。它就像一本详细的指南，列出了团队成员在SDLC期间遵循的过程，他们使用的工具，以及他们必须遵守的规则。该文档帮助每个人理解如何完成任务，并使步骤一致，以方便新的团队成员更容易跟上进度。

与过程文档相关的常见示例是待办事项、路线图、编码和测试标准、报告、会议记录、发布检查表，甚至业务通信。

因此，让我们更详细地讨论每个文档类别。

产品：系统文档

系统文档提供了解决方案的概述，并帮助工程师和涉众理解底层技术。它通常包括

产品要求,
用户体验设计,
架构,
源代码,
QA活动等

值得强调的是，这个列表并不详尽。让我们检查一下主要的系统文档。

产品需求文件(PRD)

产品需求文档或PRD提供有关系统功能和行为的信息。一般来说，需求是关于系统应该做什么以及它应该如何工作的陈述。

一个合理的做法是使用所有团队成员都遵守的单一的、一致的模板来编写需求文档。单一网页的表格有助你保持文件简洁，并节省查阅资料的时间。下面是一个单网页PRD的示例，以了解其各种元素。但是，请记住，这不是编译它的唯一方法。

Technical documentation example user interaction and design

技术文档示例:使用内容协作软件Atlassian Confluence创建的一个网页软件需求文档

以下是产品需求文档中需要包含的要点。

角色和职责。从项目参与者的信息开始，包括产品所有者、团队成员和其他关键涉众。这些细节将明确每个团队成员的职责和角色。

团队目标和业务目标。简要地定义项目最重要的目标。

背景和战略契合。对你的行动的战略目标做一个简短的解释。你为什么要开发这个产品?它将如何与公司的目标保持一致?什么是市场契合度?

假设。创建一个您计划在项目期间验证或取消的技术或业务假设的列表。

用户故事。列出或链接项目所需的用户描述。从最终用户的角度出发，用户故事是对客户行为和他们想要达到的结果的简短描述。

验收标准。这些是指示用户描述完成的条件。验收标准的主要目的是从最终用户的角度为交互场景定义一个令人满意的结果。

用户交互和设计。通常，精确的设计是在组成PRD之后创建的，因此您可以只包含产品设计的一般指导或草图。稍后，当实际设计可用时，您可以将它们链接到珠三角。

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

超出范围(不合适)。列出你在这个项目中不打算做的事情，以设定清晰的界限，防止范围蔓延。这些可以是与产品相关的功能，但不是作为这个特定项目的一部分开发的。例如，如果你建立一个电子商务网站，一个定制的移动应用程序可能是一个超出范围的项目。您还可以在这里指定额外的服务，如项目后维护，以明确您的责任。

请注意，除了PRD之外，其他类型的与需求相关的文档是为不同的目的而创建的。最值得注意的是业务需求文档(BRD)和软件需求规范(SRS)。简而言之，它们之间的主要区别在于BRD侧重于业务角度，而PRD从用户和市场的角度概述产品的需求，而SRS则提供详细的技术蓝图，说明软件应如何发挥功能以满足这些需求。

用户体验设计文档

用户体验设计(UX设计)从规划阶段开始，贯穿所有开发阶段，包括测试和发布后阶段。用户体验设计的过程包括研究、原型设计、可用性测试和实际设计阶段，在这个阶段会产生大量的文档和交付物。

研究阶段包括收集有关用户以及他们与产品交互的环境的见解。应用的技术包括用户访谈、调查、观察和市场分析。目标是了解用户的需求、行为、痛点和动机。它意味着发展

用户角色,
用户场景，以及
场景地图。

用户角色代表了潜在产品用户的关键特征，关注于行为、思维模式和动机。它们有助于定义客户细分，为不同的用户群体定制产品功能和未来的营销策略。

用户场景是描述用户角色为完成特定任务将采取的步骤的文档。用户场景关注用户将做什么，而不是概述思维过程。

场景映射用于将现有用户场景编译为单个文档。场景映射显示了每个功能在给定时刻可用的所有可能场景，以及交叉的场景步骤。

在原型设计阶段，用户体验设计师处理研究阶段的交付成果。他们开发最终产品的交互式表示，以创建和测试设计概念。在此阶段产生的一些常见文件有

站点地图
线框图
实物模型
原型
用户流程/用户旅程地图
可用性测试报告

网站/产品地图是一种视觉方案，表示产品所有页面之间的连接。它可以帮助团队可视化网站或应用程序的结构以及页面/功能之间的连接。创建站点地图是安排信息架构的一部分。

站点地图结构示例。来源:uxforthemasses.com

用户流程或用户旅程地图可视化了用户在与产品的所有部分交互时应该采取的步骤。通常，该方案包括所有的页面、部分、按钮和提供的功能，以显示用户移动的逻辑。

求职应用用户流程方案。来源:Michael Tsirakis在medium.com

线框图是未来UI的蓝图。基本上，线框图是一种方案，它显示了如何安排页面上的元素以及它们应该如何表现，但没有详细说明这些元素应该如何看起来。

Wireframe example for Peekaboo mobile app

躲猫猫手机应用的线框图示例

模型是设计创作的下一步，是代表最终产品实际外观和感觉的静态图像。

原型是一个可以与之交互的模型:点击一些按钮，在不同的页面之间导航，等等。原型可以在像Sketch或MockFlow这样的原型工具中创建。使用模板，用户体验设计师可以在开发的早期阶段创建用于可用性测试的交互式模型。

当原型用于可用性测试时，从这些会话中收集的反馈和数据将被编译成报告。

可用性测试报告有助于了解用户对原型的反应，确定痛点和需要改进的地方。报告应尽可能简短，以视觉例子为主，而不是文字。

另一个经常作为设计和开发团队之间的桥梁而创建的用户体验设计文档是风格指南。

UI风格指南是用户界面设计和实现的综合手册。它确保了整个产品的视觉表现和交互模式的一致性。样式指南定义了应该如何设计和安排UI元素和内容类型。它包括以下指南:

颜色调色板,
排版,
肖像,
布局,
按钮样式,
尺寸等。

软件架构文档

软件体系结构文档(SAD)包括解决方案架构师做出的主要体系结构决策。与上面提到的描述需要构建什么的产品需求文档不同，架构文档是关于如何构建它——每个产品组件将以何种方式贡献并满足需求，包括实现需求的解决方案、策略和方法。

因此，软件架构文档给出了产品结构的概述，并确定了工作的全部范围，将所有涉众纳入其中，并为开发团队提供了总体指导。

我们不建议太过详细地列出所有需要完成的任务，而是把重点放在高层次的描述上。

通常，SAD包括以下部分。

概述和背景。简要描述项目的主要目标，你试图解决的问题，以及你想要达到的结果。

产品描述。列出主要的功能性和非功能性需求，勾勒出项目范围。

高级架构描述。提供系统体系结构的概述，并描述主要组件及其相互作用。简要解释架构决策背后的原因以及影响您的方法的约束(例如，技术限制、遵从性需求等)也是值得的。

一个好的做法是用图表和/或其他图形材料来支持这一部分，以帮助理解和交流结构和设计原则。

Azure web应用程序架构图。来源:docs.microsoft.com

详细的系统设计。提供关于关键系统组件及其交互方式的更详细的描述。包括用于内部和外部通信的API规范和协议。概述数据体系结构、数据库模式和数据完整性。

技术策略和解决方案。定义解决横切关注点的策略，如可伸缩性、可靠性和安全性(例如，缓存、负载平衡、容错等)。

基础设施和部署。描述部署和运行系统所需的硬件和基础设施设置。包括网络布局、服务器规范和部署图。

技术设计文件（TDD）

技术设计文档(TDD)，也经常被称为技术规范，提供了关于如何实现软件系统需求的详细的、低级的信息。它在系统架构和实际代码库之间架起了桥梁，详细说明了开发人员将遵循的特定配置、接口和编码标准。

TDD包括组件设计、数据流程图、算法、API端点和交互协议，确保开发人员拥有构建软件的清晰而精确的指南。

源代码文档

源代码文档是一种直接嵌入到解决方案源代码中的技术文档。它解释了代码是做什么的，它是如何工作的，以及为什么要做出某些决定。这可以包括对算法、配置和复杂逻辑的描述。

源代码文档以注释的形式出现，可以是解释特定操作的单行注释，也可以是描述更复杂逻辑或数据结构的更大的块解释。

文档良好的代码更容易维护和调试，因为开发人员可以理解代码的意图和功能，而无需破译每一行。

质量保证文件

QA活动是任何开发项目中不可缺少的一部分。与质量保证相关的最常见的文件是

质量管理计划
测试计划
测试用例说明
测试清单

质量管理计划类似于专门用于测试的需求文档。本文档规定了产品质量所需要的标准，并描述了实现标准的方法。该计划有助于为产品经理安排QA任务和管理测试活动，但它主要用于大型项目。

测试计划是一个详细的文档，它概述了项目中预期测试活动的目标、资源、范围和时间表。它定义了QA团队的角色和职责，指定了要测试和不测试的内容，描述了要执行的测试类型(如单元测试、集成测试和系统测试)，以及要使用的方法和工具。

测试计划还包括有关测试环境设置、风险管理策略以及开始和完成测试的标准的信息。此外，它列出了预期的可交付成果，例如测试用例、报告和错误日志，并确定了负责批准计划及其结果的涉众。

该文件作为一个蓝图，以确保测试是系统的、有效的，并与项目的质量标准和目标保持一致。

通常，测试计划与测试策略会被混淆，但它们实际上是非常不同的。测试计划是一个项目级别的文档，关注于一个特定的软件产品，而测试策略是一个过程文档，它定义了整个公司采用的测试过程和标准(我们将在下面描述它)。

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

测试检查表是应该在特定时间运行的测试列表。它显示完成了哪些测试以及失败了多少测试。测试检查表中的所有点都应该正确定义。试着在检查表中将测试点分组。这种方法将帮助你在工作中跟踪它们，而不会丢失它们。如果这能够帮助测试者正确地检查应用，你便可以在列表中添加评论。

API文档

大多数产品都包含API(应用程序编程接口)，以支持与其他系统的数据交换。API文档包含所有产品API及其规范的列表。它描述了请求、响应、错误消息和其他基本细节，并告知开发人员如何有效地与系统API进行交互。

产品：用户文档

顾名思义，用户文档是为产品用户创建的。然而，他们有不同的类型，即终端用户和系统管理员。因此，您应该根据不同的用户任务及其不同的经验水平来构建用户文档。

终端用户文档

为最终用户创建的文档应该尽可能以最简单的方式解释软件如何帮助解决他们的问题。这样的用户指令可以在设备上以打印形式、在线形式或离线形式提供。

以下是用户文档的主要类型。

快速入门指南提供了产品功能的概述，并给出了如何使用它的基本指南。

完整的手册包括关于如何安装和操作产品的详细信息和说明。它列出了硬件和软件需求，功能的详细描述，关于如何充分利用它们的完整指南，示例输入和输出，以及可能的提示和技巧等。

故障排除指南向最终用户提供有关如何查找和解决在使用本产品时可能出现的问题的信息。

在线最终用户文档可能以知识库的形式出现，并包括以下部分:

常见问题
视频教程
嵌入式帮助
支持门户网站

由于用户文档是客户体验的一部分，因此使其易于理解并具有逻辑结构非常重要。用户指南用通俗易懂的语言编写，包括视觉材料和一步一步的说明，可以成为强大的营销工具，提高客户满意度和忠诚度。

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

系统管理员文档:帮助和维护指南

系统管理员文档是专门为负责计算机系统和网络的安装、配置、维护和故障排除的人员编写的。它们提供了详细的指导方针和说明，以确保IT基础设施的正常运行和安全性。

一些常见的系统管理员文档包括

安装指导,
配置手册
维护程序(包括备份和恢复过程);
安全协议(有关安全措施的指引，例如防火墙、防病毒软件和访问控制);
故障排除指南,
灾难恢复计划。

该文档对于系统管理员有效地管理和保护组织的技术资源，确保IT操作的连续性和效率至关重要。

过程文档

过程文档涵盖了围绕产品开发的所有活动。保持过程文档的价值在于使开发更有组织，更有计划。

敏捷产品路线图

产品路线图在敏捷软件开发中用于记录项目的远景、策略和总体目标。它们有助于使开发过程与初始目标保持同步。根据产品路线图的类型，它可以表达高级目标、任务优先级、冲刺时间线或低级细节。

敏捷产品团队使用的产品路线图有三种类型:

战略路线图,
技术或IT路线图，
发布计划。

战略路线图是包含项目总体信息的高级战略文件。战略路线图通常描述远景和长期目标。在敏捷产品开发的情况下，路线图可以按主题排列。主题是团队必须完成的多个任务，并且它们之间存在某种联系。例如，一个主题可能听起来像“提高页面加载速度”，这需要许多操作。

将主题周围的信息分组使路线图具有高度的灵活性和可更新性，这非常适合基于sprint的开发。关于战略路线图，最好的建议是只包括重要的信息。否则，您可能会将您的路线图变成一个笨拙的方案，难以理解和维护。

Strategic software product roadmap example

战略软件产品路线图示例。来源:productplan.com

技术路线图或IT路线图是描述技术需求和技术实现手段的底层文档。IT路线图非常详细。它们包含了每个可交付成果的信息，解释了做出这样一个决定的原因。

发布计划为发布设定了严格的时间限制。发布计划应该关注实际的截止日期，而不是指定发布细节。

发布计划示例。来源:productplan.com

强烈建议使用专用的路线图工具来创建您自己的路线图。一些在线工具如：Strategic Roadmaps(以前的Roadmunk)、 ProductPlan,、Visor或Aha! 它们为创建产品路线图提供了各种模板，并且允许快速编辑和在所有团队成员之间轻松共享。

请记住，路线图可以是陈述需求的产品文档，这取决于它的类型。它还描述了开发过程并指导您的团队完成开发。

路线图提供了一个高层次的概览和战略指导，而积压的任务侧重于实现这些更广泛目标所需的立即行动。

待办事项

待办事项是敏捷项目管理方法的基本组成部分，尤其是在Scrum这样的框架中。它们为团队在开发产品时提供了一个清晰、可操作的计划。

Scrum是如何工作的

产品待办事项列表由需要解决的任务、特性、用户描述和bug(如果有的话)的优先级列表组成。当计划任何产品工作活动时，它作为需求的主要来源。随着对产品及其用户的了解以及市场条件的变化，它通常在项目的整个生命周期中不断发展。

在类似scrum的方法中，冲刺待办事项包含开发团队在冲刺期间承诺完成的所有特定任务。它是在sprint计划会议期间创建的，因为团队根据优先级和团队的能力从产品待办事项列表中选择项目。这个待办事项列表对于每个sprint都是独一无二的，并且是一个动态文档，因为项目可以分解成更小的任务，在整个sprint中根据需要进行调整以应对挑战和变化。

有两种主要的方法来组织待办事项。扁平待办事项列表是一个简单的待办任务列表，一个功能接着一个功能。虽然它很容易创建，但它不能反映用户的旅程，并且随着它的增长而变得难以管理。

扁平的待办事项列表vs用户故事图

相反，用户故事地图将用户故事安排在二维布局中，帮助团队理解产品的功能，可视化用户旅程，并对待办事项进行优先排序。

一个将用户故事映射分解为版本的示例。来源:Netcentric

其他过程文件:计划、标准、策略等。

还有许多其他类型的过程文档值得创建，用于描述公司中的过程或反映特定项目中的特定过程。

标准包括团队在整个项目中遵循的所有编码、测试和设计标准。

计划、评估和进度表通常是在项目开始之前创建的，并且可以随着产品的发展而改变。

测试策略是描述组织整体软件测试方法的高级文档。它包括关于团队结构和资源需求的信息，以及在测试期间应该优先考虑什么。测试策略通常是静态的，因为它是为整个开发范围定义的。

发布检查表是在软件发布之前要完成的任务和检查的列表，确保没有任何重要的事情被忽略。

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

报告反映了开发过程中时间和人力资源的使用情况。它们可以按天、按周或按月生成。

一些过程文件是静态的，描述了公司对特定过程的总体方法(例如，战略、标准、检查表等)，而另一些过程文件只涉及过程的特定时刻或阶段(例如，中期报告)。结果，这些文档很快就过时了。但是它们仍然应该作为开发的一部分，因为它们可能在将来实现类似的任务或维护时变得有用。

谁编写技术文档?

为项目创建技术文档并不是一件容易的事。过程中涉及到许多不同的涉众，每个涉众都贡献了特定的专业知识和观点，以确保文档准确、全面和有用。

以下是所涉及的关键角色及其职责的列表。

业务分析师与客户密切合作，收集并定义产品必须满足的业务需求。他们还充当非技术涉众和技术团队之间的桥梁。它们确保技术文档与业务目标保持一致，并且非技术涉众可以理解。此外，ba通常有助于创建用户文档。

市场分析师从最终用户那里收集信息，以创建用户角色和用户场景。他们还研究市场，并通过验证市场契合度和业务目标为需求文档做出贡献。

项目经理监督文档编制过程，确保其与项目时间表和目标保持一致。他们负责与项目相关的大部分过程文件和计划。

解决方案架构师创建全面的架构设计文档。这些文档概述了项目的拟议体系结构，包括高层结构、软件设计以及各种组件和外部系统的集成。架构师还有助于创建技术路线图，并为项目设置技术标准和指导方针。

开发人员创建描述软件元素的源代码文档。它们还解释了特性是如何实现的，提供了代码示例，并阐明了需要记录的复杂技术过程。

UX设计师参与创建UX/UI设计文档，包括界面描述、原型、站点地图等。

QA工程师通过记录测试协议、结果和配置来做出贡献。他们确保文档反映了有效测试软件和报告错误的必要步骤。

技术作者主要负责起草和编辑文档。他们与技术专家合作，收集准确的细节，并以用户友好的格式呈现。

软件文档工具

这么长一长串的技术文档看起来确实很吓人，但你不必真的把它们写在纸上——你也不必从头开始创建它们。有很多专门的工具可以帮助你完成繁重的工作。

通用工具

软件开发团队有无数的协作工具。它们可以帮助说明需求、共享信息以及记录特性和过程。

Atlassian Confluence是最流行的协作项目工具，它拥有管理产品需求和编写文档的完整生态系统。Confluence以稳定的wiki系统和高效的用户故事管理界面而闻名。

Document 360是一个为软件即服务产品设计的自助知识库/软件文档平台。

一些。Ai是一个用于协作文档创建、存储、数据共享和使用wiki系统的工具。文档是交互式的，这意味着开发人员可以将代码块或代码片段直接嵌入到文档中，并只需单击一下即可共享。编辑完文档后，您可以将其保存为PDF或markdown格式，并将其发布到任何其他平台。

Github不需要介绍，除了那些想用它来编写软件文档的人。它为您提供了自己的wiki系统，并允许将您的文档转换为引人注目的网站展示。

Markdown编辑器

由于软件文档更容易在网络上使用，因此必须以适当的格式创建。这就是使用基于文本的标记语言的原因。最流行的一种是Markup，它可以很容易地转换为HTML，并且不需要任何特殊知识。标记在GitHub和Reddit上使用，基本上到处都是基于web的文档。

因此，这里有一些Markdown编辑器可以帮助您为项目创建文档。

Visual Studio Code是微软为Windows、Linux和macOS开发的免费开源代码编辑器。它有许多特性和扩展，包括用于项目管理和协作的特性和扩展。

Typora是一个编辑器，它提供了一个无干扰的写作环境和实时呈现markdown语法，以便于创建和编辑markdown文件。

iA Writer是一个极简主义的文本编辑器，具有简单，无干扰的界面和一系列有用的功能，包括语法高亮显示，字数统计和iCloud同步。

Quiver是一个用于Mac和iOS设备的笔记和代码片段管理应用程序。它允许用户使用文本、代码片段和标记组合来创建和组织笔记。

路线图专用工具

使用特定于路线图的工具是一个很好的做法，因为它们允许您快速共享信息，更新时间表或主题，添加新的点，并编辑整个结构。大多数路线图工具都提供了模板，因此您可以立即开始工作。

ProductPlan提供了路线图、时间线创建、协作、优先级和报告的特性，以帮助企业以更高效和有效的方式开发、共享和管理其产品路线图。

啊哈!是一套适用于整个产品管理生命周期的工具，从创意到发布——包括路线图。

Roadmunk提供自定义字段、拖放编辑、与其他工具的集成以及协作功能，使团队成员能够实时地协同工作。

KeepSolid的Roadmap Planner是另一个可视化的项目规划和团队协作工具，用于创建项目路线图，时间表和甘特图。

所有的工具都提供免费试用和付费计划，但在模板、路线图数量和你可以与之分享的人方面有所不同。

用户体验文档工具

最流行的用户体验设计工具是原型工具，它可以帮助创建草图、模型、线框图和交互式原型。

Sketch是一个简单但功能强大的矢量设计工具，它有一个web应用程序和一个Mac桌面客户端。Sketch非常有名，而且非常简单，为设计界面提供了足够的功能。

草图界面

InVision是最流行的原型工具之一。它以其协作特性和跨平台功能而闻名，这使它成为设计界面的绝佳选择。

UXPin是一个Mac和Windows设计工具，允许您构建任何类型的蓝图。你也可以上传其他产品的草图或线框图，并制作一个互动原型。

Adobe XD，其中XD代表体验设计，是一款针对用户体验专家的产品。它允许设计师创建高保真的原型，并通过应用程序分享。

API文档工具

创建API文档的过程通常是自动化的。程序员或技术编写者可以使用以下API文档生成器。

Swagger是一套用于设计、构建、记录和使用RESTful web服务的工具。它为开发人员提供了一个直观的界面，用于使用OpenAPI规范描述其api的结构，包括端点、操作和模型。这允许自动生成可实时测试的交互式API文档。Swagger的工具支持整个API生命周期，从设计和文档到测试和部署。

Postman是另一个流行的API开发工具，用于构建、测试和管理API。它还使团队能够轻松地创建、共享和维护详细的API文档。该文档是交互式的，允许用户直接从文档中执行API请求，从而简化了开发人员和涉众的测试和集成。

RAML 2 HTML是一个将RAML (RESTful API建模语言)文件转换为人类可读的HTML页面的工具。它使开发人员能够直接从他们的RAML定义生成API文档。

技术作者的工具

专业的技术作者经常使用专门的软件来创建高质量的技术文档。这样的工具被称为内容管理系统(cms)，可以更容易地构建、组织和管理各种文档。CMS可以操作不同的文件格式，导入和存储内容，并允许多个用户参与内容开发。

MadCapFlare是一个强大的基于云的软件，具有多渠道发布功能，多语言支持，广泛的学习资源等。

Adobe RoboHelp是一个全功能的CMS，允许创建富媒体内容，方便的微内容管理，协作版本控制等。

ClickHelp是一个屡获殊荣的平台，提供从其他程序轻松迁移，灵活的权限选项和许多报告功能。

软件文档的示例和模板

上一节中描述的许多工具都提供了用于创建技术文档的各种模板。

一般项目文档模板

下面的资源提供了与软件开发和项目管理相关的各种模板。

Atlassian Confluence Templates在其产品中提供了通用的项目文档模板。

ReadySET Pro是一个大型的HTML软件文档模板库，包括规划文档、架构、设计、需求、测试等等。

ReadTheDocs是一个使用ReadTheDocs平台制作的一体化模板，提供了关于编写您可能需要的每种文档类型的说明，从架构和UML图到用户手册。

TemplateLab包含数千个用于各种目的的模板-包括项目管理。

产品路线图模板

可下载的模板可能更难管理和协作，但仍然可以让您快速入门。这里有一些资源，你可以找到一些路线图模板:

Office Timeline
Template.net
SlideModel
Notion

质量保证文档模板

如果您正在寻找与qa（QA）相关的模板，您可能需要检查这里:

StrongQA.com
Template.net
QATestLab
Smartsheet

软件设计文档模板

软件设计文档有时也被称为产品或技术规范。它是软件文档中最重要的部分之一。你可以调整其中一个模板来满足你的需要:

Sample Templates
Lucidchart
Slite
cs.iit.edu
Los Alamos National Lab (.doc file download link)

专门的架构示例:AWS、Microsoft Azure和Google Cloud

如今，随着越来越多的企业倾向于迁移到云，有一些知名的可信提供商提供培训和架构示例，以促进在其环境中的操作。

Amazon——AWS架构中心为在云中运行架构工作负载提供AWS架构指导、框架、工具和最佳实践。

Microsoft -此资源提供了许多关于Azure架构的有用资料，包括示例场景、架构图等。

Google -访问Google云架构图示例的官方图标库。

如何编写软件文档：一般建议

编写足够的文档

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

考虑你的听众

尽量使您的文档简单且易于阅读。它必须具有逻辑结构并且易于搜索，因此要包含目录。尽可能避免长文本块，使用视觉内容，因为这种方式对大多数人来说更容易吸收信息。

您还必须记住文档是为谁写的。如果它是面向终端用户的，那么它肯定必须用简单的语言编写，这样读者就可以在不查阅技术词典的情况下理解它。如果文档是针对业务涉众的，那么也应该避免复杂的专业术语、技术术语或缩写词，因为您的客户可能不熟悉它们。然而，如果是针对你的技术专家团队，确保你提供了他们坚持开发计划并构建所需设计和功能所需的所有准确性和细节。

使用交叉连接

在相关文档或文档中的部分之间使用交叉链接。这对于相关信息分布在多个文件中的复杂文档集尤其有用。

交叉链接不仅可以让读者快速跳转到参考部分，而无需广泛搜索，而且有助于避免冗余和方便更新。

不要忽视词汇

文档可以专门用于内部或外部使用。在外部文件的情况下，最好对每个术语及其在项目中的具体含义提供清晰的解释。文档应该用清晰的语言传达想法，以便在涉众、内部成员和用户之间建立通用语言。

保持您的软件文档是最新的

适当的维护非常重要，因为过时或不一致的文档会自动失去其价值。如果需求在软件开发期间发生变化，您需要确保有一个系统的文档更新过程来包含变化。而且，如果在产品已经上市时发生任何更新，通知客户并刷新所有用户文档是至关重要的。

建立某种维护和更新计划是一种很好的做法。你可以定期进行更新，例如每周或每月，或者将其与你的开发计划联系起来，例如在每次发布后更新文档。自动电子邮件或发布说明可以帮助您跟踪开发团队所做的更改。

您还可以使用版本控制工具来更有效地管理此过程。它可以让你跟踪所做的更改，保留以前的版本和草稿，并使每个人保持一致。

与团队合作

敏捷方法基于协作方法来创建文档。如果你想要提高效率，就应该采访程序员和测试人员，了解软件的功能。然后，在你写完一些文档之后，与你的团队分享并获得反馈。你也可以参加团队会议，定期查看看板。为了获得更多的信息，试着发表评论，提出问题，并鼓励他人分享他们的想法和想法。每个团队成员都可以为您生成的文档做出有价值的贡献。