关于文档，还没人告诉你的那点事

2019-01-02, 5103 words, 18 min read

学习一个新的工具或者软件，首选方法是阅读开发者写的软件文档，因为 TA 最清楚怎么回事；其次是阅读最新的英文相关使用讨论或者介绍，因为中文的很多资料往往滞后；再次才是阅读中文相关介绍，而且一定要谨慎参考认真判断。评判一个工具好坏的标准之一也是其文档是否写的足够「好」。

因此无论是开发者还是用户，文档都至关重要。那到底好的文档需要包含哪些内容或者应该如何写出一个尽量好的文档呢？最近看到一篇英文博客：What nobody tells you about documentation ，以下为尽量保留作者原意的不完全翻译版本供你参考。

写在前面

无论你如何认真地写软件文档，它可能都对你的软件起不到什么帮助，除非你掌握了正确的文档写作方法。为了写好软件文档你需要了解一个秘密：「文档」不是特指某一个内容，而是有四个。

它们是：教程 (tutorials)，操作指南 (how-to guides)，说明 (explanation ) 和技术参考 (technical reference)。它们代表了四种不同的目的或功能并且需要用四种不同的方法来写，了解这一点将有助于极大改进大多数软件的文档。

一个软件有多好并不重要，因为如果文档不够好，很多人就不想使用它。

即使由于某种原因（没有第二选择）别人不得不用，如果没有规范良好的文档，使用者也不会高效地或者按照开发者想要的方式来使用。虽然几乎每个人都明白这一点，每个人也都知道他们需要一个好的文档并且试图创建一个好的文档，但是大多数人还是失败了。这并不是因为他们不够努力而是因为没有找到正确的方法。

接下来我将解释如何使你的文档变得更好，不是更加努力而是通过正确的方式。所谓正确的方法其实就是更简单的方法：更容易编写，更容易维护。

The right way is the easier way - easier to write, and easier to maintain.

有一些非常简单的原则可以指导我们进行文档编辑，但似乎又像是一个秘密很少被人们提起和总结。如果你能够将这些原则付诸实践，它就可以使你的文档变的更好，进而使你的项目、产品或团队更成功。

原则

好的文档需要包含并围绕其四个不同的功能进行构建：教程 (tutorials)，操作指南 (how-to guides)，说明 (explanation ) 和技术参考 (technical reference)。每一部分都有自身独特的写作模式，使用软件的人在不同的时间不同的情况下会需要这四种不同的文档。因此，需要围绕它们明确地来构建文档并且必须保持独立和彼此不同。

教程

学习为导向 (learning-oriented)
可以让新手轻松入门
可以理解为是一节课

如果要打个比方，就像教小朋友怎么做饭

操作指南

目标为导向 (goal-oriented)
展示如何解决特定问题
是一系列步骤

打个比方就是烹饪书中的一个食谱

说明

理解为导向 (understanding-oriented)
用来进行解释
提供各种相关的背景

打个比方就像是一篇关于烹饪历史的文章

参考

信息为导向 (information-oriented)
描述一个工具的系统方法
一定是准确而且完整的

类比的话，可以参考百科全书中的文章

以上这种分类可以使开发者和用户明白哪些信息在哪里。它告诉开发者如何写，写什么以及在哪里写，使他们免于浪费大量时间来尝试将想要传达的信息改为其他乱七八糟的形式，因为这四种文档，每一种只有一个任务。

如果这些文档没有明确地展现出自身用处和界限，想要维护一个良好的文档就是非常困难的。每种类型的文档要求都与其他三者不同。你一旦理解了这些结构它就能成为一种非常有用的工具，一方面你可以用它分析自己现有的文档，另一方面可以了解需要采取哪些措施进行改进。

教程

教程是让用户通过一系列步骤来完成某个项目的课程。它是你的软件所必须具备的，用来向初学者展示他们可以用它实现某些目的。教程完全以学习为导向，进一步讲，他们的目标是学习如何使用而不是了解你的项目。

此时你是一个老师并对学生将要做的操作负责。在你的指导下学生将执行一系列操作以达到目的。什么时候结束和进行哪些操作都取决于你，但决定一个初学者应该做什么非常困难，一方面这些操作和最终的结束点必须有意义，同时对于一个真初学者而言又要可以实现。

现在想想教孩子做饭的例子。你教孩子做了哪道菜其实并不重要，重要的是让孩子觉得做饭这件事很有乐趣并且有信心，同时还希望自己可以再来一次。通过孩子所做的事情，他将学习烹饪的一些重要事项并且将了解在厨房里使用餐具来处理食物是一种什么感觉。

使用软件（做饭）是一个「手艺」问题。它的确是知识，但它是一种实践得来的知识。当我们学习一项新的手艺或技能时，我们总是从实践开始。记住，完成教程后学习者应该就能够理解软件本身和其余的那些文档。老实说，大多数软件项目的教程都非常糟糕或者根本不存在教程。教程可以让一个学习者变成你的用户，错误或缺少教程将阻止你的软件获取新用户。不过好的教程很难写，它需要对初学者有用有意义易于参照且够强大。

如何写出好教程

允许用户通过实际操作进行学习

小时候我们都是通过实践和尝试来学习东西，比如说话或走路。在你的软件教程中学习者需要有事可做，而且他们所做的事情需要涵盖这个工具大量的操作，从最简单的操作开始再到更复杂的。

让用户走出第一步

不管初学者的第一步是复制粘贴，还是不像一个有经验的用户那样操作，或者甚至不是一个“正确的”使用方式，这些都是可以接受的。初学者的教程与最佳实践手册不同，教程的目的是让学习者开始他们的旅程而不是让他们到达目的地。

确保教程可以运行

作为老师你的一个重要工作是激发初学者的信心，有很多途径可以促成这一点，比如友好的语气和富有逻辑性的内容与资料等等。但最重要的是你要求初学者做的事必须确实可以做到。学习者需要看到你要求他们采取的操作会产生你答应他们会有的效果。如果学习者的操作产生报错或有了一个意外的结果那教程就等于失败了，即使这不是你的锅。

当你的学生和你在一起时你可以现场解决问题；如果他们自己阅读文档你就不到这一点了。所以必须提前防止这种情况发生，emm，这说起来容易做起来难。

确保用户可以立刻得到结果

**初学者所做的一切都应该是容易理解的。**如果他在看到结果之前必须做很多步难以理解的操作那就很糟糕了。每一个操作的效果都应立即展示出来，并且明确它与操作之间的联系。教程的每个部分或整个教程的结论必须是有意义的。

确保你的教程可重复

教程必须能可靠地重复，这其实不容易实现，因为人们使用不同的操作系统，经验水平也不一样。更不要说他们使用的软件或资源很可能在一段时间内会发生变化，比如版本。因此教程需要定期和详细的测试，以确保它们一直有效。

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

教程需要具体，围绕特定的操作和结果展开。引入抽象的概念通常诱惑巨大，但是所有的学习都是从特定和具体到一般和抽象。

提供最低限度的必要说明

不要解释学习者完成教程不需要知道的任何内容。扩展讨论很重要但它不是教程的作用，在教程中这反而是一个会让学习者分散注意力的绊脚石。只要有最低限度的解释就可以了，你可以链接到文档中其他地方的说明。

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

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

操作指南

操作指南使读者了解解决实际问题所需的步骤。它们是食谱，实现特定的目标。例如如何创建 Web 表单，如何绘制三维数据集，如何启用 LDAP 身份验证。

操作指南完全以目标为导向。想想一个食谱就可以，它解决了一个具体问题，我们可以假设用户已经拥有一些基本知识，他仅仅想知道如何实现某些目标。操作指南与教程完全不同，操作指南是对初学者甚至无法提出的那些问题进行的回答。

在操作指南中我们可以假设用户已经知道如何执行基本操作并使用基本的工具。让我们开心的是，不少软件文档中的操作指南往往做得都还不错。

如何写出好的操作指南

提供一系列步骤

操作指南必须包含需要按顺序执行的步骤列表（就像教程一样）。你不必从头开始而是应该找到一个合理的起点。操作指南应该可靠，但不需要具有教程那样万无一失的可重复性。

关注结果

操作指南必须注重实现目标，其它的都会让用户分析，与教程一样，详细的说明在这里也不合适。

解决问题

操作指南必须解决特定的问题，也就是「我如何。..」。这是操作指南与教程不同的地方：当涉及到操作指南时，可以假定读者知道他们应该实现什么但不知道如何实现，而在教程中你有责任决定学习者需要了解的内容。

不要解释概念

操作指南不应该进行解释，这里不是讨论的地方，它们只会妨碍用户操作。如果解释很重要请链接到该有的地方。

允许一些灵活性

操作指南应该允许用稍微不同的方式来做同样的事情。它需要足够的灵活性，用户可以看到如何应用于与你描述示例略有不同的场景，或者了解如何使其适应与你假设略有不同的系统或配置。

该结束就结束

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

认真命名标题

操作方法文档的标题应该告诉用户确切的内容并且指明是一个操作指南。比如「如何创建基于类的视图」就是一个好的标题，但是直接叫「基于类的视图」就不好了。

参考

参考是工具的技术描述和如何进行操作。

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

参考以信息为导向。技术参考可以包含示例来说明用法但它不应该尝试解释基本概念或者如何实现通用的功能。参考资料也应该是切中要害的。用烹饪类比，它可能是一篇关于某种食材的文章，描述了它的来源、化学成分和如何烹饪等等。

请注意，描述确实包括了如何使用工具的基本描述，比如如何实例化特定类或调用某个方法，或者在将某些东西传递给函数时必须采取的预防措施。然而这仅仅是其作为技术参考功能的一部分而且和操作指南也完全不同。

对于一些开发人员，参考指南是他们可以想到的唯一文档形式。他们已经了解了自己的软件并且知道如何使用它，所以他们想象其他人可能需要的就仅仅是它的技术信息。参考往往很多软件也写得很好，现在它甚至可以在某种程度上自动生成。

如何编写好的参考文档

在代码周围构建文档

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

始终如一

在参考指南中，结构，格式必须一致，与百科全书或字典一致。

只进行描述

技术参考的唯一任务是尽可能清楚和完整地描述。其他任何事情（解释，讨论，指导，推测，意见）不仅会分散注意力，而且会使其更难以使用和维护。避免使用参考来指导如何实现某种功能，并且不要对概念或讨论进行解释。如果需要，可以酌情链接到操作指南说明和入门教程中。

准确

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

说明

说明用来解释、讨论和阐明特定的一个主题，它们拓宽了文档对某一主题的覆盖范围。说明是以理解为导向的。解释同样可以描述为讨论。它可以让你从更广泛的视角，从更高层次甚至从不同角度阐明它。可以想象一个讨论文档是在闲暇时阅读的，而不是在浏览代码时阅读。

通常这部分文档很少被明确的创建，解释的片段会分散在其他部分中。其实说明和讨论不像看起来那么容易创建，它的主题不是由你想要实现的特定任务定义的（操作指南），也不是你希望用户学习的（教程），当然也不是具体的函数定义的（参考材料）。

如何写出好的说明

提供上下文

说明通常需要指明背景和上下文，有时候说明还可以解释「为什么是这样」，可能是设计决策，历史原因或者技术限制。

讨论替代方案和意见

说明也可以提供一些替代方案或同一问题的多种不同方法，甚至可以考虑并权衡相反的意见。

勿提供技术参考或指导

说明应该做的事情就是文档其他部分没有的东西。告知用户如何做某事并不是说明的任务它也不应该提供技术描述，文档的这些功能在其他部分中已经完成了。

关于文档结构

为什么分界不明显？

上文讨论的文档结构很清楚并且很有效，但通常分界没有那么明显，这是因为文档四象限中每个象限与相邻的都会有一些重叠特征。

教程和操作指南是相似的，因为它们都关注描述实际步骤；操作指南与技术参考的交集在于它们是在实际工作和编码时所需要的；参考指南和说明相似是因为它们关注理论知识；最后教程与说明的共同点是它们在我们进行学习时最有用。如下表所示：

	学习时最有用	工作时最有用
实际步骤	教程	操作指南
理论知识	说明	参考

鉴于这些重叠，不同类型的文档变得混淆并相互混合也就不足为奇了。虽然很难找到完全使用这四种结构的示例，但是大量的文档都在努力以不同的方式来完成这四个类别的任务。有些项目就完全采用了这种结构，包括 Django（虽然在早期版本中没有明确说明）和 django CMS。这两个项目中都证明了这种结构的价值。

为什么要如此分析

本文的文档结构分析基于我多年编写和维护文档的经验并花了很多时间考虑如何改进它。它还基于各种学科的合理整合，例如，教程概念具有教学基础；而且它假定存在一个老师和一个学习者，并把使用软件作为一种「手艺」来看待。

使你的文档更有用

文档维护人员必须解决的最大问题是没有清楚了解他们应该做什么，以至于他们改了又改但发现还是很难令人满意。本文讨论的文档结构通过明确的分工来解决这些问题，基于此制作的文档也更易于编写和维护，同时也更易于使用。

应该写什么，怎么写，以及把它放在哪里都变得更加清晰。

总的来说，针对四象限中的每一个文档进行明确的编写有助于软件吸引和留住更多用户同时用户可以更高效地使用，这是软件开发者最想要的东西之一。

本文作者：思考问题的熊

如果你对这篇文章感兴趣，欢迎通过邮箱或者微信订阅我的 「熊言熊语」会员通讯，我将第一时间与你分享肿瘤生物医药领域最新行业研究进展和我的所思所学所想，点此链接即可进行免费订阅。

· 分享链接 https://kaopubear.top/blog/2019-01-02-howtowritedocumentation/

数据科学