# 解决什么问题

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

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

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

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

# 文档的分类

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

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

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

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

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

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

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

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

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

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

孩子做饭

我们可以这样去写教程：

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

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

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

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

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

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

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

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

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

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

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

百科参考

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

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

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

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

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

参考资料

我们可以这样去写解释：

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