博主译自What nobody tells you about documentation

不管你在文档上做了什么，它都不会正确的说明你的软件——除非你用正确的方法去做

为了编写好的软件文档，有四个需要知道的原则，少了其中之一，那么就不能称之为文档

这四个原则分别是：教程、指南、说明和参考（demo）。它们有着四个不同的目的或功能，并且需要四种不同的方法来创建它们。了解这一点的含义，通常会极大的有助于改进大多数软件文档。

引言

你的软件有多好并不重要，但是如果文档不够好，人们就不会使用它。

哪怕由于某种原因他们不得不使用，没有好的文档，他们也不会有效地，或者按照您希望的方式去使用。

直到最后，大多数人都没能正确地使用它。

通常，这并不是因为他们做的不够，而是因为他们没有正确的用法。

在本文中，我将说明如何使文档变得更好。这不会让编写更复杂，而是以正确的方式进行。正确的方法是更容易的方法。使得文档更容易编写与维护。

有一些非常简单的方式去管理资料，但这些资料很少被做成文档。即使我们不应该这样做，这也似乎是个技巧。

一个承诺：如果你能把这些原则付诸实践，它将使你的文档更好。你的项目、产品或团队也能更成功。

技巧

文档需要包括并围绕其四个不同的功能进行组织：教程、指南、说明和参考（demo）。他们每个都需要一种独特的写作方式。使用软件的人在不同的时间、不同的环境下需要这四种不同的资料，所以软件通常都需要它们。

教程

• 有助于学习
• 帮助新人起步
• 一个课堂

比喻：教小孩如何做饭

指南

• 有目地的
• 说明如何解决特定问题
• 有一系列的步骤

比喻：烹饪书中的食谱

说明

• 有理解导向
• 说明内容
• 提供背景与环境

比喻：讲述烹饪历史的文章

参考

• 面向信息
• 系统的描述
• 准确的并且完整的

比喻：参考百科全书文章

这种划分使得作者和读者都能清楚地知道信息在哪里。它告诉作者如何写，写什么，写在哪里。因为每种文档都只会编写一次，所以它节省了作者花费大量时间试图将他们想要传递的信息转换成读者能够理解的。

事实上，维护良好的不隐式或显式这类方案的资料，是极其困难的。每种类型的需求与其他类型的需求不同，因此，任何试图保持这种结构的文档都会受到影响。因为它同时会产生不同的结果。

一旦您理解了结构，它就能成为分析现有资料，以及理解需要做什么来改进的非常有用的工具。

关于项目资料

您很可能会问：像变更日志、贡献策略和其他有关项目的信息之类的东西在哪里比较合适？答案是它们不能放在文档里面，因为它们，严格来说，是项目资料，而不是软件本身的文档。

它们可以简单地保持在适当命名的部分旁边的项目资料中-只要他们不混在里面。

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

1.教程

教程是让读者通过一系列步骤来完成某类项目的课程。它们是你的项目所需要的，以便向初学者展示他们可以用它来获得一些东西。它们完全是以学习为导向的，具体来说，它们倾向于学习如何学习而不是学习。

你是老师，你要对学生所做的事负责。在你的指导下，学生将执行一系列动作以达到某种目的。虽然结束和行动取决于你，但也决定他们应该是什么样的工作。结束必须是有意义的，对于一个完整的初学者来说也是可以实现的。

想想教孩子做饭的比喻。你教孩子做饭并不重要。重要的是让孩子觉得快乐，并获得信心，并希望再做一次。通过孩子们做的事情，他们会学到烹饪内的重要内容。他们将了解在厨房里，如何使用餐具来处理食物。

这是因为使用软件，同如烹饪，是工艺问题。它是知识—-—但它是实践性的知识，而不是理论性的知识。当我们学习一种新的技艺或技巧时，我们总是通过动手学习。

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

大多数软件项目都有很差的或不存在的教程。教程是将你的学习者变成用户的工具。一个错误的或缺少的教程将阻止您的项目获取新用户。

好的教程很难编写。他们需要对初学者有用，易于跟踪，有意义和内容极其丰富。

如何编写好教程？

让用户通过做来学习

一开始，我们只是通过做什么来学习任何东西——这是我们学会说话或走路的方式

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

让用户开始

如果你的初学者的第一步是抱婴儿的步骤,这是完全可以接受的。如果你让初学者做的不是一个有经验的人会做的，或者即使不是“正确”的方法，这也是完全可以接受的——初学者的教程与最佳实践的手册不是一回事。

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

确保你的教程质量

作为导师，你的工作之一是激发初学者的信心：用软件，在教程的帮助下，当然也要依托他们自己的能力，让他们知道能够实现什么效果。

有很多事情促成了这一点。友好的语调有助于语言的连贯使用，以及通过材料的逻辑发展。但最重要的是，你要求初学者做的事情必须工作。学习者需要看到你要求他们采取的行动具有你所说的效果。

如果学习者的行为产生错误或意想不到的结果，你的教程失败了——即使这不是你的错。当你的学生和你在一起时，你可以拯救他们；如果他们独自阅读你的文档，你无能为力。所以你必须防止这种情况提前发生。这无疑是说起来容易做起来难。

确保用户立即查看结果

学习者所做的每件事都应该完成一些可以理解的事情，无论多么小。如果你的学生必须在看到结果之前做两页奇怪的、不可理解的事情，那就太长了。每一个动作的效果应尽可能清晰可见，与动作的联系要清楚。

一个教程的每一个部分的结果，或者作为一个整体的教程，必须是有意义的成就。

让你的教程复用

您的教程必须可靠复用。这不容易实现：人们将使用不同的操作系统、经验和工具来实现它。更重要的是，他们可能使用不同的软件或资源。

教程必须每一次实现他们所做的。

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

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

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

引入抽象的诱惑是巨大的，毕竟大多数计算使用了这个概念。但是，所有的学习都是从具体的和具体的到一般的抽象的，并要求学习者在掌握了具体的教学效果之前，就要学会抽象的抽象程度。

提供最精简的必要的说明

不需要说明任何事情，学习者不需要知道怎么去完成教程。在所有教程中，扩展的讨论很重要。在一个教程中，它是一个障碍和分散注意力。只有最低限度是适当的。相反，可以链接到文档中其他地方的说明。

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

你的教程需要集中在手头的任务上。也许你介绍的命令有很多其他的选择，或者可能有不同的方式来访问某个API。没关系：现在，你的学习者以便取得进步，不需要知道这些。

2.指南

指南是读者通过解决现存问题所需的步骤。

它们是实现特定目的的方法，例如如何创建Web表单；如何绘制三维数据集；如何启用LDAP身份验证。

它们完全是以目标为导向的。

如果你想类比，想想食谱，准备一些吃的东西。食谱有明确的定义。它解决了一个特定的问题。它展示了一个人——可以被假定拥有一些基本的知识——如何实现某事。

指南是非常不同的教程。指南是一个真正的初学者可能无法解决的问题的答案。在指南中，你可以假设一些知识和理解，你可以假设用户已经知道如何做基本的事情和使用基本工具。

如何在软件文档中指导是相当好的。它们也很有趣，很容易写。

如何编写好指南？

提供一系列步骤

指南必须包含一系列的步骤，需要遵循的顺序（就像教程）。你不必从头开始，只是在一个合理的起点。那么指南应该是可靠的，但他们不需要如教程具有复用性。

关注结果

指南，必须着眼于实现一个切实可行的目标。别的都是分散注意力的事。在教程中，详细的解释在这里是不合适的。

解决问题

指南必须解决一个特定的问题或问题：我如何…？

这是指南不同于教程的一种方式：当谈到指南时，读者可以假定知道他们应该实现什么，但是还不知道如何实现——而在教程中，您负责决定读者需要了解什么。

不要解释概念

指南不能解释事情。这不是讨论这种问题的地方，他们只会妨碍行动。如果解释很重要，就联系起来。

允许一些灵活性

指南应该允许做相同的事情有稍微不同的方式。它需要足够的灵活性，以便用户可以看到它将如何应用于与您描述的示例稍微不同的示例，或者理解如何将其应用到与您假设的系统或配置稍微不同的系统或配置。别这么明确，除了你心中所想的确切目的外，其他的导向都没有用。

忘掉完整的事情

实用性比完整性更有价值。教程需要是完整的，端到端的指导，但指南不是。它们可以在你看来合适的地方开始和结束。他们不需要提及所有的事情，只是因为它与主题有关。一个臃肿的指南不能帮助用户快速地找到解决方案。

给他们起好名字

指南的标题应该告诉用户它到底做了什么。如何创建基于类的视图是一个很好的标题。创建基于类的视图或更糟糕的基于类的视图不是。

3.参考

参考机械的说明和如何操作它。参考只有一项工作：描述。它们是由代码决定的，因为最终这就是它们所描述的：键类、函数、API，因此它们应该列出诸如函数、字段、属性和方法之类的东西，并列出如何使用它们。

参考资料是面向信息的。

无论如何，技术参考可以包含示例来说明使用，但是它不应该试图解释基本概念，或者如何实现公共任务。

参考资料应简明扼要。

烹饪类比可能是一篇百科全书关于一种配料的文章，描述它的来源、行为、化学成分，以及如何烹饪。

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

对于一些开发人员来说，参考是他们能想象到的唯一一种文档。他们已经了解他们的软件，他们知道如何使用它。他们能想象到其他人可能需要的是关于它的技术信息。参考资料往往写得很好。它甚至可以在某种程度上自动生成，但这本身是不够的。

如何编写好的参考文献？

在代码周围构造文档

为参考资料提供与代码库相同的结构，以便用户可以同时浏览代码和文档。这也将帮助维护人员看到引用文档丢失或需要更新的地方。

始终如一

在参考文献中，结构、声调、格式必须是一致的——与百科全书或词典一致。

只做描述

技术参考的唯一工作是尽可能清楚和完整地描述。其他任何东西（解释、讨论、指导、猜测、观点）不仅会分散注意力，而且会使它更难使用和维护。在适当的时候提供例子来说明描述。

避免使用参考资料来指导如何实现超出使用软件的基本范围的事情，并且不允许开发概念解释或主题讨论。相反，可以适当地链接指南、说明和介绍教程。

准确

这些描述必须准确并保持最新。机器和你的描述之间的任何差异都不可避免地会导致用户误入歧途。

4.说明（解释）

说明，或讨论，澄清和阐明一个特定的话题。它们拓宽了文档对某一主题的覆盖范围。他们是以理解为导向的。

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

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

讨论不像看上去那么容易创建。当你有了某人问题的起点时，说明起来会很简单，但当你有一个空白页面，并且必须写下关于它的东西时，说明起来就不那么容易了。

说明主题不是由您想要完成的特定任务（如操作指南）或希望用户学习的内容（如教程）定义的。它不是机械定义的，比如参考材料。它由您认为可以同时覆盖的合理区域来定义，因此用于讨论的主题的分割有时可能有点武断。

如何写出好的说明？

提供上下文

说明处于背景和上下文的位置。例如，Web表单以及如何在Django或Search and django CMS中处理它们。它们也可以说明为什么事情是这样的——设计决策、历史原因、技术约束。

讨论备选方案和意见

说明可以考虑替代方案，也可以考虑多个不同的方法来解决同一问题。例如，在Django部署的一篇文章中，考虑和评估不同的Web服务器选项是合适的。讨论甚至可以考虑并权衡相反的观点。例如，测试模块是否应该在包目录中。

不要指导或提供技术参考

说明相关的事情，在文档的其他部分。主题地方不是说明用户如何做某事的地方。也不应提供技术说明。文档的这些功能已经在其他章节中得到了呈现。

关于结构

为什么区分不明显

这种结构是清楚的，并且是可行的，但是有一个原因为什么它不那么明显，那就是文档的每个象限的特征与方案中相邻象限的特征重叠的方式。

教程和操作指南是相似的，因为它们都涉及描述实际步骤，而操作指南与技术参考的共同之处在于，它们是我们在实际工作、编码时所需要的。参考指南和说明是相似的，因为它们与理论知识有关，最后，教程与说明的共同之处在于，它们在我们学习时最有用，而不是实际工作：

鉴于这些重叠，不奇怪的是，不同类型的文档变得相互混淆和混淆。尽管很难找到完全使用它的明确示例，但是大量的文档以不同的方式识别这四个功能中的每一个。一些项目完全采用它，包括Django（虽然这不是早期版本中明确的）和Django CMS。它在两个项目中都证明了其价值。

关于分析

本文中的文档分析是基于多年的文档编写和维护经验，以及花费大量时间考虑如何改进它。它也基于来自各种学科的健全原则。例如，它的教程概念具有教育学基础；它假定教师和学习者，并且认为使用软件是一种从处理细节的具体步骤中抽象理解一般原则的手段。

做好文献工作

文档维护人员必须处理的最大问题之一就是不清楚他们应该做什么。他们写和改写，但发现很难使它以令人满意的方式组合在一起。这种结构通过明确区分和分离来解决这些问题。他们制作更容易编写和维护的文档，使用起来更容易，也能找到自己的方法。

哪怕文档不是自己编写的，但是现在可以编写它了，并且不必担心不适合、不清楚范围或者怀疑应该包括什么或者采用什么样式。写什么，写什么，放哪里，变得更清楚了。它更好地为用户服务，因为对于他们与软件交互周期的所有不同阶段，他们会找到合适的文档类型，满足当时的需求。

编写明确和明确地处理这四个象限中的每个象限的文档有助于软件吸引并留住更多的用户，他们将更有效地使用它。这是软件创建者最想要的事情之一。

版权属于：谁把年华错落成诗 所有，转载请注明出处！

本文链接：https://blog.pomears.com/archives/31.html

如果博客部分链接出现404，请留言或者联系博主修复。