RTFM？如何写一本值得一读的手册

定义： RTFM （请阅读F'ing手册 ）。有时，讽刺的是，它被翻译成“ 阅读精美手册” ，这是对那些提出以下问题的人说的：开明的人认为我们是在有尊严地回答下，而不是在我们有尊严的情况下，作为挤压新手自我的机会。

您是否注意到某个特定的开放源码社区告诉您RTFM的频率越高，则FM可能越差？我多年来一直在考虑这一点，并得出结论，这是因为耐心和同理心是良好文档记录的基础，就像它们是成为一个正派人的基础一样。

首先，一些免责声明。

尽管我从事开源文档工作已有近20年的时间，但我没有经过实际的培训。有一些人在做，还有一些很棒的书，如果您关心这些东西，就应该阅读。

首先，我推荐Anne Gentle的《对话与社区》。而且，如果您正在寻找有关此内容的会议，那么我建议您有两个： Write Docs和OpenHelp 。

这篇文章的标题来自凯西·塞拉（ Kathy Sierra），他在几年前的一次演讲中有一张幻灯片说：“如果您想让他们使用RTFM，请做一个更好的FM。” 但是我们该怎么做呢？

开源世界有一个共同的智慧：每个人都知道文档太糟糕了，没有人愿意编写它，而事实就是如此。但事实是，有很多人想要编写文档。我们只是让他们难以参与。因此，他们在Stack Overflow，他们的博客和第三方论坛上写文章。尽管这可能很好，但这也是最坏实践的解决方案蓬勃发展并获得动力的好方法。拥抱这些人并将其作为项目的正式文档工作的一部分，具有许多优势。

与写作小说不同，在小说写作中，流行的建议只是开始写作 ，而对于技术写作，则需要进行一些计划。在开始之前，您应该问几个问题。

WHO？

这些中的第一个是谁？。你在写信给谁？一些专业的技术作家会创建角色，以便他们在写作时可以自己思考：“在这种情况下，莫妮卡需要了解什么？” 或“ Marcus可能围绕该主题遇到什么样的问题？” 然后相应地写。

在此过程的这一点上，记住并非所有听众都由年轻，白人，说英语的人组成，他们长大后观看Monty Python是至关重要的。

附件A：Python文档

Python文档充满了Monty Python参考资料：

现在，请不要误解我：Python文档在大多数情况下都很棒。但是我有一个抱怨–内部笑话。 Monty Python的幽默贯穿了所有文档，这是一把双刃剑。内在的笑话会形成一种社区感，因为您会开玩笑，因此您处于内心。除非您不在。在这种情况下，内在的笑话会明显地表明您不在内心。在这里仔细踩一下。考虑包括一个解释笑话的参考指南，如果鹦鹉死了，请指向YouTube视频：

口语化也是如此。

附件B： PHP文档

在PHP docs的此示例中，引用了英语谚语： 在大海捞针中寻找针头，以使该示例更易于理解。如果您以英语为母语，那么该示例就很好，因为它使哪个参数是哪个显而易见。但是，对于不是英语为母语的读者，该示例指出他们不是目标受众，这可能会对吸引新人进入您的社区产生寒蝉效应。

哪里？

下一个要问的问题是在哪里？ 。是的，您需要在您的项目网站上有文档，但是对话还在哪里进行？除极少数情况外，其他站点（例如StackOverflow ）都是项目的事实上的文档。而且，如果您真正希望为用户提供帮助，则需要去他们所处的位置。如果他们在Twitter，Facebook或AOL上提问，则需要去那里，在那里回答他们的问题，并为他们提供指向官方文档的指针，以便他们下次知道在哪里看。

您无法控制人们在哪里进行对话，而尝试进行对话将被视为与您的听众脱节。（尽管我是这个话题，但无论如何，他们不是您的听众。）

有一次，当我为一位前雇主工作时，我们发现听众在Facebook上而不是在我们的网站上进行对话。那些当权者决定我们必须停止这一点，然后我们建立了自己的内部社交网站。然后我们告诉所有人，在讨论我们的组织时，他们必须使用它而不是Facebook。我怀疑您能猜出对我们有多好。

但是，当您忽略StackOverflow，Twitter和各种第三方网站上的受众时，您会做同样的事情，因为它们的位置不正确。

什么？

继续讲力学。你应该写什么？

范围

您必须决定的第一件事（是的，您需要决定这一点，因为不一定有一个正确的答案）是您的文档范围。那就是：您愿意涵盖哪些主题？当然，这意味着其他所有内容都超出范围，应该将其推送到其他人的文档中。

例如，在Apache Web Server文档中，我们有一个名为Getting Started的文档，该文档介绍了开始之前需要了解的内容。本文档的目的是画一条线，说明超出本文档范围的内容，同时还使人们了解实际上涵盖了这些内容的资源。因此，HTTP规范，DNS的内部工作原理和内容（例如HTML和CSS）绝对不在文档范围内，但是使用Apache Web Server的每个人都需要了解这些内容。

文件类型

一旦确定了范围以及要写给谁，就可以为它们编写几种不同类型的文档。 Anne Gentle将它们归类为：

从这里开始

就像我之前提到的《 入门指南》文档一样，在这里您可以告诉用户在开始使用之前需要了解的内容。

参考指南

参考指南是全面的，通常很干燥。在这里定义术语，解释功能的输入和输出，并给出示例。语气是事实，而且要切合实际。没有太多的讨论或对话。声音通常是非个人的。

讲解

教程会牵着你的手，引领你走下这条路。他们向您展示了每个步骤，并偶尔坐在小路旁的长椅上，解释特定步骤的原理。他们之间的对话非常热烈，有时甚至是ty不休。声音是个人的；您正在与先前的角色阶段中定义的特定人员讲话。

学习/理解

学习/理解文档通常与教程相关，因此会进行更深入的研究。他们调查特定事物的原因和方式。为什么要做出某个决定？它是如何在代码中实现的？这个东西的未来会是什么样？您将如何帮助创造未来？这些文档有时最好作为博客文章而不是作为正式文档的一部分，因为它们可能会严重分散试图解决问题的人们的注意力。

食谱/食谱

烹饪书通常是O'Reilly技术书目录中最畅销的部分，这是有原因的。人们需要解决方案，现在就需要解决方案。文档的食谱或食谱部分应为常见问题提供剪切和粘贴的最佳实践解决方案。他们应该附有解释，但是您应该了解，大多数菜谱用户都会剪切并粘贴解决方案，这对他们来说将是最终的结果。

您的大部分观众只关心解决他们的迫在眉睫的问题，因为这就是他们获得报酬的全部，并且您需要了解这是完全合法的需求。当您组装新的宜家书桌时，您不必担心为什么选择了特定的螺钉尺寸，而只需要这些说明，就可以期望它们起作用。

因此，对示例进行测试至关重要。不管示例多么琐碎，您都必须对其进行测试并确保它可以完成预期的工作。花了许多令人沮丧的时间来试图弄清楚为什么文档中的示例不起作用，而几分钟的测试就会发现冒号应该是分号。

食谱还应促进最佳实践，而不仅仅是最简单或最快的解决方案。永远不要告诉他们怎么不这样做，因为他们只会剪切和粘贴，然后在比当他们开始更糟糕的修复。

我最喜欢的网站之一是“ 我修复了它” ，它展示了解决问题的人的独创性，而他们并未过多考虑解决方案的可能后果，他们只是想解决问题。

错误讯息

是的，错误消息也是文档。实际指向解决方案的有用错误消息可节省数小时的搜寻和挫败感。

考虑以下两个错误消息：

`ERROR. FORBIDDEN`

和

`Access forbidden by file permissions. (ERRNO 03425)`

首先是令人震惊，但无济于事，将需要大量研究以找出为什么禁止这样做。第二种方法告诉您它与文件权限有关，并且具有错误号的额外好处，您可以在Google上找到许多详细介绍如何解决此问题的文章。

哲学

整个思路源自多年的技术支持渠道，包括IRC，电子邮件，正式文档，Usenet等。那些掌握答案的人，我们似乎想让新来的人很难受。毕竟，我们在雪地里上山步行去学校，然后赤着脚回来，还记得吗？我们通过阅读代码和试验来弄清楚如何使事情正常进行。我们为什么要让这些孩子更轻松呢？他们应该像我们一样被迫赚钱，对吧？

技术世界每天都变得越来越复杂。人们期望知道的事情清单在不断增长，没有人可以成为一切专家。期望每个人都完成所有功课并提出明智的问题不仅是不合理的，而且变得不可能了。

丰富的技术支持以及更好的文档资料是人们有效使用软件的唯一途径。而且，如果他们不能在合理的时间内获得答案，他们将使用另一种解决方案，该解决方案具有更好的准入门槛。

在他的Perl编程Perl书籍的第一版中，Perl编程语言的创建者和那个社区的父亲Larry Wall开玩笑说程序员的三个美德：懒惰，不耐烦和傲慢：

关于这个笑话的解释值得一读，但是请记住，这些是程序员的美德，就其作为程序员而言，与计算机有关。拉里（Larry）在1999年出版的《开源：开源革命的声音》一书中解释说，作为一个与他人相关的人，我们应该追求的三个美德是：勤奋，耐心和谦卑。

当我们在帮助有技术问题的人时，急躁被视为傲慢。 “我的时间比你的问题更重要。” 傲慢被认为是轻浮的。和懒惰？好吧，那只是懒惰。

耐心和友善，帮助人们以自己的步调（即使感觉很慢）也被视为尊重。无论您身在何处，都欢迎他们，并耐心地帮助他们迈向新的高度，这是您建立社区的方式。

不要让人们感到愚蠢：这必须是一个核心目标。

即使世界上其他所有人都是混蛋，您也不必如此。

文件
碟

本文是Rikki Endsley协调的Doc Dish专栏的一部分。 要撰写本专栏文章，请提交您的故事创意或通过open@opensource.com与我们联系。

翻译自: https://opensource.com/business/15/5/write-better-docs