欢迎转载，提出意见。

原文传送门

What nobody tells you about documentation Author: Daniele Procida

image

不管你多么努力地编写文档，它都可能低于我们预期。我们想要事半功倍的效果，唯有用正确的方法。

一些小诀窍能助我们写出优秀的软件文档。实际上，软件领域没有一种东西称作文档，而是如下名称： 教程、操作指南、解释和技术参考。它们有不同目的、功能，且编写也有不同方式。了解这些方式将极大的改进大多数软件文档。

教程

软件是否有文档并不重要。因为 如果说明文档不够好，没人会去用它们。 当然也有例外的情况:如软件没有可替代者，我们依然会用有着糟糕文档的软件。退一步讲，即使我们使用它们，也没有按照期望的方式-高效应用。

几乎每个人都知道他们需要好的文档，而且大多数人尝试编写好的文档，结果却是：意与愿违。失败和努力与否无关，而是没有使用正确的方式编写文档。

本文说明如何以正确的方式写更好的文档，且这种方式更易于书写和维护。

原则上，管理文档一些规则非常简单，但它们很少被提及或详细说明。这些规则似乎以秘密的形式存在。

小诀窍

文档需要围绕四种不同功能组织：教程、指南、解释和技术参考。每一个都需要不同的写作模式。不同的时间、不同的环境下，我们要用到不同的文档，所以4种文档都需要编写。

教程 (TUTORIALS)

特点如下：

• 以学习为目的
• 适合新手入门
• 是一个课程
  教程类似于如何教会小朋友做饭。

如何编写指南

特点如下:

• 以目标为导向
• 指南用于解决特定的问题
• 包括一些列的步骤，按步骤进行。
  指南类比成：烹饪书上的菜谱，说明每道菜特定的步骤，每道菜的工序。

解释文档

解释文档特点：

• 以理解作为基本的导向
• 说明问题、解释问题
• 描述问题的背景和关联内容
  解释可以类比成：一篇讲述烹饪社会历史的文章。

技术参考

技术参考是一个参考指南。
特点如下：

• 提供丰富的信息
• 描述工作的原理
• 文档要准确且完整

一份参考文档类似于：这方面技术的百科全书

按照这样划分，用户有很清晰意识到如何对信息进行组合。作者也知道 怎么写， 写哪些内容 ，写作的导向。同时，为了让这些信息显得更有意义，作者可以花费更多时间在如何挖掘信息上，而不是收集每一类信息。

每一类文档只有一个职能。

事实上，如果我们没有明确或者有意识的识别出文档应用领域，很难编写、维护好一份文档。在文档编写时，任何不区分对象和应用领域的尝试都将事与愿违。

一旦我们接受这种方法(按照职能进行分类)，它变成了一个非常有用的工具：用于分析现有的文档,以及如何做去改进它们。

项目文档

你也许有这样疑问：像变更记录、发布策略、以及其他关于项目的信息应该放在哪里？从严格意义上讲，这些内容要放在项目文档中，而不是软件文档中。
只要不把它们和软件文档混在一起，它们就可以被保存在同一文档里。让我们探索这4类文档编写方法。

教程

教程一门课程。它通过一系列步骤“手把手”的帮助读者完成某种类型的项目。对项目而言，它是向初学者展示项目的功能。

教程完全以学习为导向，具体来说，它倾向于教授如何学习(learning how)，而不单单是传授学习知识（learning that）。

教程就如同老师，它教授学生以后要怎么做。在教程指导下，学生通过执行一系列的动作来达成某些目标。

教程决定了结果，用户以后的行为。确定结果和行为包含的内容，可能是一项艰巨的工作。因为对初学者而言，结果不但是“有意义的”，而且也是“可实现的”、可操作的。

如果以教授孩子做饭为例。教授做饭并不重要。真正重要的是让孩子发现其中的乐趣，获取自信，并且期待再一次尝试。

孩子们通过这样的形式，学到关于烹饪的重要知识。孩子们会了解厨房是什么样子的，如何使用餐具和处理食物。

使用软件，就像做饭一样 是一项技巧。它也是知识——但它是实用的知识，而不是理论的知识。当我们学习一门新手艺或技能时，我们总是从实践中开始学习。

教程的目的是：在学习完成之后。学习者理解应用，以及软件本身。大多数软件项目都有非常糟糕的(或者根本没有)教程。教程引导学习者变成用户。而一个糟糕或缺失的教程将让这部分客户流失。

好的教程很难写好。它即要对初学者非常友好、又容易学习、也要非常健壮。

如何写好教程

让用户通过实践学习

一开始，我们通过实践来学习——就像我们如何学会说话或走路的方式。
软件教程就是让用户进行操作和实践。所不同的是教程包含一些工具和由浅入深的操作步骤。

用户实践

初学者开始实践是像婴儿学步一样发自习惯。教程关键点是让学习者* 开始他们的旅程 *，而不是以成功完成所有步骤为目的。

确信教程有效

教程的目的和责任是：是激发、培养初学者的信心:对软件、教程和对他们完成要求的信心。

很多东西有助于达成这个目标。如：友好的语调，语言的连贯使用，以及材料的逻辑合理性。但是最重要的是，你要求初学者做的事情必须是可行的。学习者需要看到你让他们采取的行动有你所说的效果。

如果用户行为产生错误或者不可预料的结果，即使不是教程本身的问题，那么教程也是不合理。当用户和你在一起时，你可以帮助他们;但如果他们是自己阅读文档，你就不能帮助他们—所以你必须提前防止不可预期的问题发生。毫无疑问，这说起来容易做起来难。

让用户立刻看到效果

无论多么琐碎的操作，用户做的每件事都是可理解的。**如果用户在看到结果之前必须做很多奇怪的操作或不可理解的事情，那么这一步教程就太长了。每一个实践的结果越快看到越好，和实践和结果的联系也需是明确的。

教程从整体和局部来看，都必须是一个有意义的。

实践过程具备重复性

教程必须是能可靠地重复操作。这很难实现：人们使用不同的操作系统，拥有不同的经验和使用工具能力存在差异。 更重要的是，他们使用任何软件或资源很可能发生变化。所有这些教程都必须支持这些变化。因此，教程需要定期和详细的测试，以确保它们正确。

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

教程需要把特定的、特殊的行为和结果具体化。当然，引入抽象的诱惑是巨大的; 毕竟抽象能够解决和解释很多问题。 但是学习过程是从特定和具体到一般和抽象，并且学习者让他们掌握具体内容之前，能够理解抽象层次。这是不好教学例子。

提供最低解释

仅向用户解释为了完成教程需要的知识。扩展讨论很重要 - 只是不在教程中。 对用户而言，解释是理解教程的障碍。 只有最低限度是合适的。 合理的做法是：在需要的地方适度解释。

关注用户需要的实践

教程需要专注于当前的任务。也许您引入的命令有许多其他选项，或者可能有不同方法来访问某个API。 那些都是不必要的。现在，学习者取得进步不需要了解那些无关的内容。

如何编写操作指南

指南给读者解决实际问题提供所需的步骤。它们就像食谱用来实现特定目标 - 例如：如何创建Web表单; 如何绘制三维数据集; 如何启用LDAP身份验证。这部分说的指南是操作指南。

指南完全是以目标为导向。

如果你想要一个比喻，想想一个要准备食谱。食谱上有清晰明确的菜单，用户明白今天的 菜单列表。指南是在假设用户拥有一些基本知识前提下，来说明如何实现这些目标。

指南与教程完全不同。 它无法解决真正的初学者的问题，不适合初学者。在指南中，假定用户有一些知识 -- 假定用户已经知道如何执行基本操作并使用基本工具。软件文档中的指南可以写的很好， 它们很有趣且易于编写。

如何编写优秀的指南哪？

提供一系列步骤

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

关注结果

操作指南必须注重如何获得结果，其它都是次要的。 与教程一样，它不需要有详细的解释。

解决问题

指南必须解决特定问题。与教程不同的在于：当涉及到操作指南时，可以假设读者知道他们应该实现什么但是还不知道如何做 - 而在教程*负责决定读者需要了解的内容。

不要解释概念

指南不应解释和操作无关内容。不应该在指南进行解释; 解释只会妨碍用户的理解。 如果解释很重要，请在其它地方进行。

适度的灵活性

**操作指南允许稍微不同的方式来实现相同的功能。 **它需要足够的灵活性，用户看到它将如何应用于与您描述的示例略有不同的示例，或者了解如何使其适应与您假设的略有不同的系统或配置。 除非你想到的确切目的，否则不要具体化。

不要面面俱到

实用性比完整性更有价值。教程需要是完整的，端到端的指南; 指南则没有这样的限制。 它可以在适合地方开始和结束，它也不需要提及所有的内容，只涉及相关联的内容即可。 臃肿的指南无法帮助用户快速获得解决方案。

切题的标题

文档标题要告诉用户它的确切功能。 如何创建基于类的视图是一个很好的标题。但 创建基于类的视图或，基于类的视图则表达文档的功能。

参考指南

参考指南是条理性的技术说明及其如何操作的方法。

参考指南唯一的作用就是：叙述。它描述的是：关键类，函数，API等等。所以它列出函数，字段，属性和方法等内容，并说明用法。

参考指南是信息导向，也就是传递信息。参考参考包含示例来说明如何使用，但不应该尝试解释基本概念，或者如何实现通用任务。

参考指南是严肃而中肯(austere and to the point)。

和烹饪做类比，参考指南是百科全书，说明其来源，其行为，其化学成分，如何被烹制等。

参考指南提供一些基本功能：如何使用这种机制 - 如何实例化特定类，或调用某种方法，或者传递给函数时采取的预防措施。 然而，这是其作为技术参考部分功能，它不要与操作指南混淆。

对于一些开发人员而言，参考指南是他们唯一想得到文档。 他们已经了解软件，知道如何使用它。 参考指南是他们认为是提供关于软件的技术信息。

参考材料往往写得很好。 它甚至可以在某种程度上自动生成，只是还做的不够好。

如何编写优秀的参考指南

围绕代码构建文档

参考指南与代码库保持相同的目录结构，以便用户能够代码和文档相互对照。 这也将有助于维护人员查看参考文档缺少的部分或需要更新部分。

一致性

在参考指南中，布局，笔调，格式 与要与同类百科全书或字典的保持一致。

只进行阐述

参考指南的唯一目标是尽可能清楚，完整地描述。 其他任何事情（解释，讨论，指导，推测，意见）不仅会影响阅读，而且会使其更难以使用和维护。 在适当时候，参考可以提供示例用以说明。

如下情况要避免发生：使用参考指南来指导如何进行实现；关于软件使用之外的介绍；不允许对主题的概念或讨论进行解释。 当然，在需要的地方，可链接到操作指南，说明和入门教程。

准确性

文档描述必须准确且保持最新状态。 实现和描述之间的任何差异都将不可避免地导致用户"误入歧途"。* *

解释文档

解释用于澄清和阐明特定主题。 为了让用户理解软件和原理，它*延伸文档对主题说明范围。

解释同样可以描述为讨论。 它从更广的视角，从更高层次甚至从不同角度阐明软件。 解释文档可以在闲暇时阅读，而不用关注代码和实现。

软件解释文档很少明确占据文档的章节，而是作为片段分散在文章中。 有时，解释文档存在于如背景或其他注释，且没有明确解释文档的功能。

解释、讨论不像看起来那样容易编写。当你从问题出发直接解释原因，或者在白纸上，直接写出问题答案的时候，也不是件容易的事情。

解释主体不是根据特定的任务去设定，例如操作指南，或者您希望用户学习的内容，例如教程。 它不是讲原理，比如参考指南。 它是由你认为是一个合理的区域来定义的，因此，解释有时包含主观色彩。

如何编写优秀的解释文档

提供上下文

解释一般在说明背景和连接上下文 - 例如，* Web表单以及如何在Django 或 Search和django CMS 中处理它们。它们解释为什么*事情是如此 - 设计决策，历史原因，技术限制。

讨论替代方案和意见

解释提供替代方案，或问题的不同解决方案。 例如，在关于Django部署的文章中，考虑和评估不同的Web服务器选项是合适的，讨论甚至可以考虑并权衡相反的意见 - 例如，测试模块是否应该在包目录中。

不要指导或提供技术参考

解释包含文档的其他部分没有的功能。这不提供用户如何做某事的解释。 它也不提供技术描述。 这些功能已在其他部分中处理。

关于文档结构

为什么不明确？

以上提到的4个部分，这样的结构清晰而有效，但存在一个问题：文档每个功能(象限)特征与相邻象限特征重叠。如下

what_nobody_tells_you_about_documentation.png

教程和操作指南类似，因为它们都关注描述实际步骤，而操作指南与技术参考交集是我们在工作层面，编码。 参考指南和说明是相似的，因为它们关注理论知识，最后，教程与解释的共同之处在于它们在我们学习时最有用 *，但却不是实际应用：

122.PNG

因为这些重叠，不同类型文档变得混淆甚至相互混合也就不足为奇了。

大量文档呈现四个象限中一个，按照4个象限完全区分开很难找到，虽然很难找到例子。Django是符合文档结构的例子：Django , and django CMS.

关于分析结论

本文中文档分析基于多年编写和维护文档的经验，并花了很多时间考虑如何改进它。 例如，教程概念具有教学基础; 它假定一个导师和一个学习者，并考虑使用软件作为一种工艺，其中对一般原则的抽象理解遵循处理细节的具体步骤。

编写文档

文档维护人员必须处理的最大问题是：没有清楚地了解他们应该做什么。 他们不断修订文档，但发现很难让它以令人满意的方式融合在一起。以象限的方式结构化文档，是通过分离文档功能来解决这些问题。这样，文档更易于编写和维护，更易于使用并且可以找到解决方法。

以功能分离结构编写文档，让文档的内容、如何编写、以及如何组织文档更加的清晰。它更好地为用户服务，对于与软件交互的周期中的所有不同阶段，用户将找到适合当时需求的正确文档。

我们有针对对四个象限中的每一个的编写文档有助于吸引和留住更多的用户，他们将更有效地使用如软件，这也是软件提供商最想要的东西之一。