软件文档

软件文档是每个软件项目的重要组成部分，但这可能是一项艰巨的任务。它耗时，有时很乏味，而且不是开发新软件中令人兴奋的部分。然而，它对于让您的业务起步至关重要。

在创建公司第一份或第一百份软件文档时，不要依赖猜测或复制他人的做法。糟糕的软件文档可能会赶走潜在客户，同时也会浪费公司资源。相反，应采用最佳实践，例如利用内部经验和减少行话，来创建能够提升而非贬低您的程序的技术文档。

到底什么是软件文档？

软件说明材料是为帮助用户或开发人员理解软件特性和功能而准备的任何文档。这类技术文档包括文本说明、视频、用户指南和培训手册，旨在帮助用户理解软件的特性、操作和功能。

软件文档有两个目标受众：软件工程师和产品最终用户。在软件工程中，文档指的是帮助专业人员理解产品规划、编码和实现的信息和出版物。这些文档使开发人员能够从头开始理解、更新和定制软件。

软件文档描述了软件开发人员在开发产品时所做的工作，以及 IT 专业人员和客户在安装和使用产品时必须做的事情。手册通常被集成到软件的用户界面中，也作为帮助手册的一部分提供。数据通常按任务类别组织，其中包括以下内容：

• 评估
• 规划
• 设置或安装
• 定制
• 管理
• 使用与维护

软件文档的类型

根据目标受众的不同，软件文档可以有多种形式。下面提供了一些常见的例子。

• 管理记录

软件开发需要为所有相关人员提供文档，特别是负责监督和推动流程的产品或项目经理。管理文件可以包括项目文档，如指南、路线图、产品规格，以及项目信息，如进度报告和会议记录。

最终用户/客户文档：最终用户文档是面向客户的一种流程文档，解释如何使用、安装和配置您的程序。提供这类文档有助于人们理解如何使用您的程序。最终用户文档的例子包括用户指南、信息数据库、说明书、故障排除手册、参考指南和发布说明。

• 开发人员文档

开发人员文档是描述您的软件应如何工作的产品文档，以便开发人员了解他们正在开发什么。这些文件包括构建需求（描述程序预期功能）、架构信息（描述程序的组件和特性）以及清单（帮助开发人员完成软件开发过程）。

• “即时”文档"

“即时”（JIT）文档策略涉及按需创建文档，并在用户需要时提供支持文件。它建立在敏捷方法之上，并侧重于客户反馈。如果您发布一个软件，您只创建必要数量的文档，而不是基于对消费者需要帮助的假设而建立一个信息库。当您的客户遇到问题或疑问时，您将解决方案添加到文档中，并在他们的流程中提供这些资源，使他们能够保持高生产力，并成为您产品的自给自足的用户。

JIT 文档的例子包括知识库、常见问题解答网站、操作手册以及关于如何添加功能的文档。您可以使用即时方法更新您的程序，而无需创建一套新的文档。

软件文档的目标是什么？

编写软件文档的基本目的应该是让客户和开发人员的生活更轻松。您还应该努力实现以下目标：

提供有益的最终用户支持：文档通常是用户与您的程序功能首次接触的切入点。它应该帮助您的用户理解如何安装和使用您的程序。您的文档也应该简单明了、组织良好。最终用户支持是将用户需要的所有数据集中在一个地方，这样他们就不必为了弄清楚您的程序如何工作而在网站之间来回跳转。

向开发人员提供文档说明：如果开发人员手头有文档说明，他们更有可能实现您的项目目标。这些文档为他们指明了正确的方向，并节省了他们的时间，因为他们不需要项目主管或其他相关方的大量帮助。

呈现重要的产品数据：产品文档必须向用户和开发人员提供有关您产品的关键信息。例如，您的程序应包括重要功能、所需的软硬件兼容性规格、安装方法以及用户可能需要的任何其他相关数据。

有效沟通：我们可以向团队成员、利益相关者和最终用户传递关键事实，增进各方之间的理解与合作。

保持一致性：通过明确我们的程序和流程，我们可以确保整个组织内的任务完成方式保持一致。

文档记录了我们所有的决策、结果和过往经验，让人们可以从中学习，并将其用作未来的参考点。

提高效率：一个既定的系统可以帮助我们减少模糊性，简化我们的流程和操作。

降低风险：通过提供指导和最佳实践，有效的文档可以帮助我们识别潜在问题并降低风险。

如何编写有效的文档

一段优秀的代码类似于一份好的文档。简短、基础、直接。以下是一些需要考虑的准则：

• 确定文档的受众。它只针对程序员吗？是否有更广泛的市场？了解这一点将为您节省时间，因为您可以提前知道在解释中需要解释多少内容。
• 撰写简短但描述性强的背景故事，详细说明您的创作的关键特征。这将帮助读者理解该项目的目标，并确定其与他们正在寻找的主题的相关性。
• 列出并描述您功能的主要方面，务必提及与其他功能的任何依赖关系。
• 确保有时间戳，向读者表明文档是最新的。此外，如果您使用了某些存档，请确保包含它们的最新版本。
• 慷慨地提供代码示例，解释如何使用您创建的功能，并展示预期的结果。

良好软件文档的优势

编写软件文档的基本目的应该是让用户或开发人员的生活更轻松。您还应该努力实现以下目标：

鼓励用户采用：编写良好的文档通过更高效的用户引导帮助您的用户快速入门，并利用您的程序提供的所有功能。当您的消费者无需中断正在做的事情就能找到所需信息时，他们更倾向于继续使用您的程序，从而提高您产品的数字采用率。

为开发人员提供指导：产品文档使开发人员能够阐明他们在创建产品时所做的决策。当他们以后回头查看代码时，指导方针可以帮助他们回忆起当初为什么要这样开发。对于可能最终从事相同软件工作的其他程序员来说，这也非常有益。

减轻软件支持团队的负担：软件文档通过减少用户的支持请求和电话数量来帮助支持人员。它还有助于故障排除，因为当信息以消费者自助服务的形式轻松获取时，他们可以提供更快、更全面的客户支持。

客户更满意：程序文档帮助您的用户理解程序的所有复杂性，使他们能够更有效率和效率。对您的软件满意的客户会成为共同所有者，投资于您的业务，并成为您最强的拥护者。

更高质量：软件文档可以帮助确保软件创建过程是可靠和可重复的，并提供创建过程中所做决策和行动的记录。这有助于通过防止故障和错误来提高应用程序的整体质量。

提高效率：产品文档可以通过提供关于产品的简洁、一致和最新的数据，帮助开发人员以及其他技术利益相关者更有效地工作。例如，开发人员可以利用文档快速获取所需信息，节省尝试逆向工程源代码或弄清楚产品工作方式的时间。

软件文档最佳实践

在生成文档时遵循最佳实践至关重要，以确保所有内容都以易于理解的方式编写，为用户提供价值，并符合项目目标。在开发文档时，请牢记以下推荐做法：

编写易于理解的文档：您的软件信息应以清晰的语言编写，不应包含行业术语。它也应适合您的目标受众。例如，在编写技术文档时，使用开发人员会使用的语言和短语。

考虑您的目标受众：在编写软件文档时，定义目标受众至关重要，因为您的读者将决定文档的主题和设计。对于计算机文档，不同的目标群体会有不同的需求和期望，理解这些需求和要求对于生成成功的文档至关重要。

例如，如果您想要制作的文件的目标受众是程序的最终用户，那么手册应该用清晰简洁的语言编写，并为典型活动提供分步说明。它还应包括有关产品特性和功能的信息，以及帮助用户理解如何使用该软件的示例和练习。

• 优先考虑您的用户。您可以从公开的用户信息开始，并与支持等面向客户的部门交谈。
• 确定用户的目标（例如，安装数据库）。
• 为您的目标受众创建人物画像。
• 制定受众定义（例如，入门级管理员受众）。
• 创建产品用例（例如，在 CRM 平台中管理业务客户）。
• 为您的用户选择最佳的分发格式（例如，FAQ、wiki 或信息库）。
• 创建具有适当广度和深度的材料。
• 确定哪些人将为您的文档提供反馈。
• 进行用户研究并与他们互动。

定义边界和目标：在确定受众之后，确定文档的范围和目的。这使您能够专注于最重要的信息，同时确保书面材料是最新且有用的。例如，您可以选择专注于某些功能或应用程序，或者您可能希望提供执行特定活动所需的信息。

制定内容策略：下一步是设计如何创建所需的软件文档以匹配上一阶段确定的范围和目标，以及谁将负责更新文档。这可能包括制定编写和更新记录的时间表，以及定义所需的资源和工具。该策略还可以包括评估和修改文档的程序，以确保其正确和最新。

制定风格指南：您应该考虑为您的软件文档建立一个风格指南，就像您为任何内容推广工作所做的那样。

考虑在软件的文档风格指南中包含以下项目：

• 术语标准化（您如何称呼您的组织和软件）
• 语气和语调
• 页面布局（标题、段落和列表的使用）
• 措辞建议（应该是 Internet 还是 the web —— 显然是前者！）
• 图形和视频的使用

您的文档应包含什么内容？

Tom Preston-Werner 的“自述文件驱动开发”是一种常用技术。它需要在开始编写任何代码之前创建一个 Readme 文件。该文件可作为您程序内容的指南，通常包含：

• 对您的应用程序功能及其如何解决问题的描述
• 一个展示您的代码如何在常规情况下使用的示例
• 指向源代码和错误跟踪器常见问题解答的链接，以及请求帮助的途径，以及安装您的程序许可信息的说明
• 然而，在我看来，提供能够真正帮助使用其软件/库的开发人员的优秀文档，应该远远超出传统的自述文件。

结论

编写好的文档很困难，但当您考虑到使用它的人应用您的软件功能会变得多么简单时，这一切都是值得的。这反过来又会增加您产品的受欢迎程度，使其更具吸引力，并可能催生一个开发者生态系统，他们渴望投入时间深入了解它，并为其发展、稳定性和长久性做出贡献。