跳到主要内容

如何写好文档

· 阅读需 10 分钟

你的产品有多好并不重要，因为如果它的文档不好，人们就不会使用它。即使他们因为别无选择而不得不使用它，如果没有好的文档，他们也不会有效地使用它或按你希望的方式做。

几乎每个人都明白这一点。几乎每个人都知道他们需要好的文档，大多数人都试图创建好的文档。但大多数人都失败了。

这不是因为他们不够努力，而是因为他们没有以正确的方式做这件事。

用正确的方法可以使你的文档更好。正确的方法也是更简单的方法——更容易编写，更容易维护。

文档的分类​

文档需要包含并围绕其四个不同的维度进行分类：教程、操作指南、参考指南和解释。它们中的每一个都需要不同的写作模式。使用软件的人在不同的时间、不同的情况下需要这四种不同类型的文档。

不同类型的文档需要围绕它们的目标维度构建，并且能彼此区分。

教程操作指南参考指南解释
文档目的学习达成一个目标相关信息深入理解
必要内容允许新手入门展示如何解决特定问题描述体系架构详细的解释
文档形式一节课一系列的操作步骤干货详细论证
例子教小孩子做一道菜烹饪大全中的一个食谱参考的百科全书资料烹饪有关的社会历史的文章

这种划分使作者和读者都清楚用什么材料，要怎么样用材料，达到什么目标。它告诉作者如何写，写什么，在哪里写。它使作者免于浪费大量时间 试图将他们想要传递的信息变成一个有意义的形状，因为每一种文档只有一个目标。

一旦你理解了这个分类结构，它就会成为一个非常有用的工具：用来分析现有文档，并了解需要做些什么来改进文档。

教程​

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

读者完全以学习为导向，具体来说，他们以学习怎么做而不是学习本身为导向。

重要的是，完成本教程后，学习者就可以理解文档的其余部分以及软件本身。

大多数软件项目都有非常糟糕或根本没有教程。教程可以将你的学习者转变为你的用户。一个垃圾的教程或者没有教程将阻止你的项目获得新用户。

在四种文档的中，教程是最多也最长的，它最难做好。最好的教学方法其实是让老师在场直接教学生。但这几乎是不可能的，我们的教程充其量只是一个远非完美的替代品。

教程需要对初学者有用，让初学者容易照着做，并始终保持更新。

孩子做饭

我们可以这样去写教程：

  • 允许用户边做边学
  • 让用户能入门
  • 确保教程是有效
  • 确保用户照着做后立即看到效果
  • 教程可重复操作
  • 专注于具体的步骤，而不是抽象的概念
  • 提供最低限度必要的解释
  • 只关注用户需要采取的步骤

操作指南​

操作指南的目的是引导读者解决实际问题，比如：如何创建 Web 表单;如何绘制三维数据集;如何启用 LDAP 认证。

操作指南完全以目标为导向，它与教程完全不同，不应该与教程混淆。教程是你告诉初学者需要知道的内容，操作指南是给具有一定经验的用户解决问题的答案。

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

与教程不一样，软件文档中的操作指南一般都做得相当好。它们很容易写。

菜谱

我们可以这样去写操作指南：

  • 提供一系列操作步骤
  • 注重操作的结果
  • 要解决特定问题
  • 不需要解释概念
  • 允许操作有一定的灵活性
  • 只关注操作本身
  • 取一个直观的标题

参考指南​

参考指南是机器及其操作方法的技术描述。

参考指南只有一个目的：描述。它们是代码决定的，内容就是所描述的：关键类、函数、API，因此参考指南应该列出函数、字段、属性和方法等内容，并说明如何使用它们。

参考资料以信息为导向，要简朴而中肯。无论如何，技术参考可以包含示例来说明用法，但它不应试图解释基本概念或如何实现常见任务。

比如，描述包括如何使用机器的基本描述：类似如何实例化特定类或调用某个方法，或者在将某些内容传递给函数时必须采取的预防措施。然而，这只是其作为技术参考功能的一部分，并且不要与操作指南混淆。参考指南描述软件的正确用法，而操作指南展示如何使用它来实现某个目的。

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

参考资料往往很好写，因为在某种程度上，它甚至可以自动生成，但这本身并不够。

百科参考

我们可以这样去写参考指南：

  • 围绕代码构建文档
  • 结构、语气、格式都必须保持一致
  • 尽可能清晰和完整地描述
  • 准确并保持最新

解释​

解释或讨论、澄清、阐明特定主题。它们扩大了文档对主题的覆盖范围。

解释以理解为导向。它不是由要实现的特定任务（如操作指南）或你希望用户学习的内容（如教程）定义的。它也不是由机器的一部分定义的，比如参考材料。

解释同样可以等价为讨论;它们本质上是话语性的。它们从更高层次甚至不同的角度阐明它。你可能会想象讨论文档是在闲暇时阅读的，而不是在代码上阅读的。

文档的解释很少单独创建，相反，解释片段会分散在其他文档的部分中。诸如“背景”或“其他注释”或“关键主题”之类的名称。

参考资料

我们可以这样去写解释：

  • 在背景和上下文的地方写
  • 用于考虑替代方案
  • 补充其他文档没有提到的内容

通过以上介绍，我们在书写相应文档时，只要尽量遵循这些指导方向，就可以写出更好的软件文档。