如何撰写技术文档

原文来自 What nobody tells you about documentation ，本文是本人整理翻译而成。

关于如何写好一个完善的软件文档，这里应当是有四要素，而不是一个。它们分别是：教程，操作指南，说明和技术参考。它们代表四种不同的目的和功能，并且需要四种不同的方法来创建它们。了解这一点的含义有助于改进大多数的软件文档-通常会有非常好的效果。

前言

软件有多好并不重要，因为如果文档不够好，人们就不会使用它。

即使由于某种原因他们不得不使用它，这是因为他们没有选择，没有良好的文档，他们将不会有效地使用它或者你喜欢它的方式。几乎每个人都明白这一点。 几乎每个人都知道他们需要良好的文档，并且大多数人都试图创建好的文档。但大多数人都失败了。通常这不是因为他们不够努力，而是因为他们没有找到正确的方式。

在本文中，我将解释如何使您的文档更好，而不是通过更加努力，而是通过正确的方式。 正确的方法是更简单的方法 - 更容易编写，更容易维护。

有一些非常简单的原则可以管理少见的有拼写的文档。 它们似乎是一个秘密，尽管它们不应该是。如果您能够将这些原则付诸实践，它将使您的文档更好，您的项目，产品或团队更成功 - 这是一个承诺。

文档需要包含并围绕其四个不同的功能进行构建：教程，操作指南，说明和技术参考。 他们每个都需要一种独特的写作模式。 使用软件的人在不同的环境中需要这四种不同的文档 - 因此软件中通常都需要它们。并且需要围绕它们明确地构建文档，并且它们必须保持独立且彼此不同。

这种划分使作者和读者明白了哪些信息在哪里。 它告诉作者如何编写，编写什么以及在何处编写它。 它使作者免于浪费大量时间来尝试将他们想要传达的信息篡改成有意义的形状，因为这些文档中的每一种只有一个工作。

事实上，维护良好的文档非常难以隐含或明确地识别该方案的象限。 每种类型的要求都与其他要求不同，因此任何未能保持这种结构的文档尝试都会受到影响，因为它会立即被拉向不同的方向。

一旦理解了结构，它就成为一种非常有用的工具，用于分析现有文档，并了解需要采取哪些措施来改进它。

关于项目文件您可能会问：更改日志，贡献策略以及有关项目的其他信息在哪些方面适合此方案？ 答案是他们没有 - 因为严格来说，他们是项目文档，而不是软件本身的文档，

它们可以简单地与其他材料一起保存在适当命名的部分中 - 只要它们没有混合在一起。

考虑到这一点，让我们探讨四个关键功能中的每一个。

教程

教程是让读者通过一系列步骤来完成某种项目的课程。 它们是您的项目所需要的，以向初学者展示他们可以用它实现某些目标。

他们完全以学习为导向，具体而言，他们的目标是学习如何而不是学习。

你是老师，你负责学生的工作。 在您的指导下，学生将执行一系列操作以达到目的。

结束和行动取决于你，但决定他们应该做什么可能是艰苦的工作。 最终必须有意义，但对于一个完整的初学者也是可以实现的。

考虑一个教孩子做饭的比喻。

你教孩子做饭的内容并不重要。 重要的是，孩子觉得它很有乐趣，并且有信心，并希望再次这样做。

通过孩子所做的事情，它将学习烹饪的重要事项。 它将了解在厨房里使用餐具来处理食物是什么感觉。

这是因为使用像烹饪这样的软件是一个技巧问题。 它是知识 - 但它是实践知识，而不是理论知识。 当我们学习新工艺或技能时，我们总是开始学习它。

重要的是，完成教程后，学习者就能够理解其余的文档和软件本身。

大多数软件项目都有非常糟糕或不存在的教程。 教程将使您的学习者变成用户。 错误或缺少的教程将阻止您的项目获取新用户。

好的教程很难写。 它们需要对初学者有用，易于遵循，有意义且极其健壮。

允许用户学习

一开始，我们只是通过做才学到任何东西 - 这就是我们学会说话或走路的方式。

在您的软件教程中，您的学习者需要做的事情。 在学习本教程时，他们所做的不同事情需要涵盖广泛的 工具 和操作，从最简单的工具和操作开始，再到更复杂的工具和操作。

让用户开始

如果你的初学者的第一步是手持婴儿步骤，这是完全可以接受的。 如果初学者要做的不是有经验的人的方式，或者即使它不是“正确的”方式，那也是完全可以接受的 - 初学者的教程与最佳实践的手册不同。

教程的目的是让学习者开始他们的旅程，而不是让他们到达最终目的地。

请确认您的教程工作

作为导师，你的一个工作就是激发初学者的信心：在软件，教程，导师中，当然，还有他们自己实现所要求的能力。

有很多事情可以促成这一点。 友好的语气和语言的一致使用以及材料的逻辑进展都有所帮助。 但最重要的是，你要求初学者做的事必须奏效。 学习者需要看到你要求他们采取的行动会产生你说他们会有的效果。

如果学习者的动作产生错误或意外结果，那么您的教程就会失败 - 即使这不是您的错。 当你的学生和你在一起时，你可以拯救他们; 如果他们自己阅读你的文档你就不能 - 所以你必须提前防止这种情况发生。 毫无疑问，这说起来容易做起来难。

确保用户立即获得结果

学习者所做的一切都应该是可以理解的，无论多么小。 如果你的学生在看到结果之前必须做两页的奇怪和难以理解的事情，那就太长了。 每一个行动的效果应尽快显现和明显，并且应明确与行动的联系。

教程的每个部分或整个教程的结论必须是有意义的成就。

使教程可重复

您的教程必须可靠地重复。 这不容易实现：人们将使用不同的操作系统，经验和工具水平来实现它。 更重要的是，他们使用的任何软件或资源很可能在此期间发生变化。

每次教程都必须适用于所有这些教程。

不幸的是，教程需要定期和详细的测试，以确保它们仍然有效。

关注具体步骤，而非抽象概念

教程需要具体，围绕特定的，特定的行动和结果。

引入抽象的诱惑是巨大的;毕竟大多数计算是如何获得它的力量的。但是所有的学习都是从特定的，具体的到一般的和抽象的，并且要求学习者在他们甚至有机会掌握具体内容之前欣赏抽象层次是教学不好。

提供最低限度的必要解释

不要解释学习者为了完成教程而不需要知道的任何内容。扩展讨论很重要 - 只是不在教程中。在教程中，这是一个障碍和分心。只有最低限度是合适的。相反，请链接到文档中其他地方的解释。

只关注用户需要采取的步骤

您的教程需要专注于手头的任务。也许您引入的命令有许多其他选项，或者可能有不同的方法来访问某个API。没关系：现在，你的学习者不需要了解那些才能取得进步。

操作指南

操作指南使读者了解解决实际问题所需的步骤。

它们是食谱，实现特定目标的方向 - 例如：如何创建Web表单; 如何绘制三维数据集; 如何启用LDAP身份验证。

他们完全以目标为导向。

如果你想要一个比喻，想想一个食谱，准备吃东西。

配方有明确的定义结束。 它解决了一个具体问题。 它表明某人 - 可以假设他已经拥有一些基本知识 - 如何实现某些目标。

操作指南与教程完全不同。 操作指南是对真正的初学者甚至无法制定的问题的回答。

在操作指南中，您可以假设一些知识和理解。 您可以假设用户已经知道如何执行基本操作并使用基本工具。

提供一系列步骤

操作指南必须包含需要按顺序执行的步骤列表（就像教程一样）。你不必从一开始就开始，只是在一个合理的起点。操作指南应该可靠，但它们不需要具有教程的铸铁可重复性。

关注结果

操作指南必须注重实现实际目标。别的什么都是分心。与教程一样，详细说明在这里不合适。

解决问题

操作指南必须解决特定的问题或问题：我如何...？

这是操作指南与教程不同的一种方式：当涉及到操作指南时，可以假定读者知道他们应该实现什么，但还不知道如何 - 而在本教程中，您有责任决定读者需要了解的内容。

不要解释概念

操作指南不应该解释事情。这不是那种讨论的地方;他们只会妨碍行动。如果解释很重要，请链接到它们。

允许一些灵活性

操作指南应该允许稍微不同的方式来做同样的事情。它需要足够的灵活性，用户可以看到它将如何应用于与您描述的示例略有不同的示例，或者了解如何使其适应与您假设的略有不同的系统或配置。除非你想到的确切目的，否则不要那么具体，指南对任何事情都没用。

随时离开

实际可用性比完整性更有价值。教程需要完整，端到端的指南;操作指南没有。它们可以在适合您的地方开始和结束。他们不需要提及所有要提及的内容，只是因为它与主题相关。臃肿的操作指南无法帮助用户快速获得解决方案。

标题对用户友好

操作方法文档的标题应该告诉用户确切的内容。如何创建基于类的视图是一个很好的标题。创建基于类的视图或更糟糕的是，基于类的视图不是。

技术参考

技术参考是机器的技术说明以及如何操作。

技术参考只有一个工作：描述。它们是由代码决定的，因为它们最终描述的是：关键类，函数，API等等，它们应该列出函数，字段，属性和方法等内容，并列出如何使用它们。

参考资料是面向信息的。

通过各种方式技术参考可以包含示例来说明用法，但它不应该尝试解释基本概念，或者如何实现共同任务。

参考资料应该是严格的，切中要害的。

烹饪类比可能是一篇关于一种成分的环球文章，描述了它的来源，它的行为，它的化学成分，它是如何烹饪的。

请注意，描述确实包括如何使用机器的基本描述 - 如何实例化特定类，或调用某个方法，或者在将某些东西传递给函数时必须采取的预防措施。然而，这仅仅是其作为技术参考的功能的一部分，并且强调不要与操作指南相混淆 - 描述软件的正确使用（技术参考）与显示如何使用它来实现某一目的不同（方法文档）。

对于一些开发人员，参考指南是他们可以想象的唯一文档。他们已经了解他们的软件，他们知道如何使用它。他们可以想象其他人可能需要的是关于它的技术信息。

参考材料往往写得很好。它甚至可以在某种程度上自动生成，但这本身就不够了。

构建代码周围的文档

为参考文档提供与代码库相同的结构，以便用户可以同时导航代码和文档。这也将有助于维护人员查看缺少参考文档或需要更新的位置。

始终如一

在技术参考中，结构，音调，格式必须一致 - 与百科全书或字典一致。

不要做任何描述

技术参考的唯一工作是尽可能清楚和完整地描述。其他任何事情（解释，讨论，指导，推测，意见）不仅会分散注意力，而且会使其更难以使用和维护。提供示例以在适当时说明说明。

避免使用参考材料来指导如何实现事物，超出使用软件的基本范围，并且不允许对主题的概念或讨论进行解释。相反，请酌情链接到操作指南，说明和教程。

准确性

这些描述必须准确并保持最新状态。机器与您对它的描述之间的任何差异都将不可避免地导致用户误入歧途。

说明

说明或讨论，阐明和阐明特定主题。它们拓宽了文档对主题的覆盖范围。

他们是理解导向的。

说明同样可以描述为讨论。它们是文档放松和退回软件的机会，从更广泛的视角，从更高层次甚至从不同角度阐明它。您可以想象一个讨论文档是在闲暇时阅读，而不是在代码上阅读。

这部分文档很少明确创建，相反，解释的片段分散在其他部分中。有时，该部分存在，但有一个名称，如背景或其他笔记，并没有真正公正的功能。

讨论不像看起来那么容易创建 - 当你有一个问题的起点时，直接解释的东西就不那么容易了，当你有一个空白页面并且必须写下一些关于它的东西时。

主题不是由您想要实现的特定任务定义的，例如操作指南，或者您希望用户学习的内容，例如教程。它不是由一块机器定义的，比如参考材料。它是由您认为一次尝试覆盖的合理区域定义的，因此讨论主题的划分有时可能有点武断。

提供上下文

说明是背景和上下文的位置 - 例如，Web表单以及如何在Django或Search和django CMS中处理它们。

他们还可以说明为什么事情如此 - 设计决策，历史原因，技术限制。

讨论替代方案和意见

说明可以考虑替代方案，或同一问题的多种不同方法。例如，在关于Django部署的文章中，考虑和评估不同的Web服务器选项是合适的，

讨论甚至可以考虑并权衡相反的意见 - 例如，测试模块是否应该在包目录中。

请勿指导或提供技术参考

说明应该做的事情是文档的其他部分没有的。指示用户如何做某事并不是解释的地方。它也不应该提供技术描述。文档的这些功能已在其他部分中处理。