定义：RTFM（Read The F'ing Manual，阅读他妈的手册）。有时它被讽刺地渲染为 Read The Fine Manual（阅读精美的手册），这句话是那些问了问题的，在我们这些开明人士看来，回答这些问题有损我们的尊严，但借此机会打压一下新手的自尊心却不有损尊严的人说的。
您是否注意到，一个特定的开源社区越频繁地告诉您 RTFM，FM 就可能越糟糕？我多年来一直在思考这个问题，并得出结论，这是因为耐心和同理心是编写优秀文档的基础，就像它们是成为一个正派的人的基础一样。
首先，一些免责声明。
虽然我从事开源文档工作已经快 20 年了，但我没有接受过任何实际的培训。有些人接受过培训，并且有一些很棒的书籍，如果您关心这些东西，您应该阅读一下。
首先，我推荐 Anne Gentle 的 《Conversation and Community》（对话与社区）。如果您正在寻找关于这方面的会议，我建议参加两个会议：Write The Docs 和 OpenHelp。
本文的标题来自 Kathy Sierra，她在多年前的一次演讲中放了一张 幻灯片，上面写着：“如果你想让他们 RTFM，那就写一本更好的 FM。” 但我们该如何做到这一点呢？
开源世界有一个普遍的共识：每个人都知道文档很糟糕，没有人想写文档，而且情况就是这样。但事实是，许多人想写文档。只是我们让他们参与变得太难了。所以他们在 Stack Overflow、他们的博客和第三方论坛上写文章。虽然这可能很好，但这也是最差实践的解决方案蓬勃发展并获得势头的好方法。接纳这些人，让他们成为您项目的官方文档工作的一部分，有很多好处。
与小说写作不同，小说写作的普遍建议是直接开始写，但对于技术写作，您需要稍微计划一下。在开始之前，您应该问自己几个问题。
谁？
第一个问题是谁？。您是为谁写作？一些专业技术作家会创建 人物角色，以便他们在写作时可以这样想：“莫妮卡在这种情况下需要知道什么？” 或“马库斯可能在这个主题上遇到什么样的问题？” 然后据此写作。
在这个过程的这个阶段，记住并非所有的受众都是年轻、白人、说英语的男性 他们从小就看 Monty Python 长大 至关重要。
案例 A：Python 文档
Python 文档 中充斥着 Monty Python 的梗
现在，不要误解我的意思：Python 文档在很大程度上是很棒的。但我对它有一个抱怨——内部笑话。Monty Python 式的幽默贯穿整个文档，这是一把双刃剑。内部笑话形成了一种社区意识，因为您get 到这个笑话了，所以您就在圈内。除非您没有 get 到。在这种情况下，内部笑话鲜明地指出您不在圈内。在这里要小心谨慎。考虑包含一个参考指南，解释这些笑话，并且，在死鹦鹉的例子中，指向一个 YouTube 视频
对于俗语也是如此。
案例 B：PHP 文档
在这个 来自 PHP 文档的例子 中，英语谚语 finding a needle in a haystack（大海捞针）被引用，以努力使例子更易于理解。如果您是以英语为母语的人，这个例子很棒，因为它清楚地表明了哪个参数是哪个。然而，对于那些不是以英语为母语的读者来说，这个例子指出了他们不是目标受众，这可能会对将新人引入您的社区产生寒蝉效应。
哪里？
接下来要问的问题是哪里？。是的，您需要在您的项目网站上提供文档，但对话还在哪里发生？除非在极少数情况下，其他网站，例如 StackOverflow，是您项目的实际文档。如果您真的关心帮助您的用户，您需要去他们所在的地方。如果他们在 Twitter、Facebook 或 AOL 上提问，您需要去那里，在那里回答他们的问题，并给他们指向官方文档的链接，以便他们知道下次在哪里查找。
您无法控制人们在哪里进行对话，试图这样做会被视为与您的受众脱节。（当我在谈论这个话题时，他们无论如何都不是您的受众。）
有一次，当我在一家前雇主那里工作时，我们发现我们的受众在 Facebook 上进行对话，而不是在我们的网站上。当权者决定我们必须阻止这种情况，我们建立了自己的内部社交网站。然后我们告诉所有人，他们在讨论我们的组织时必须使用它——而不是 Facebook。我猜您能猜到这对我们来说效果如何。
但是，当您忽略 StackOverflow、Twitter 和各种第三方网站上的受众时，您也在做同样的事情，因为他们不在正确的地方。
什么？
接下来是机制。您应该写些什么？
范围
您必须决定的第一件事（是的，您需要决定这一点，因为不一定有一个正确的答案）是您的文档范围是什么。也就是说：您愿意涵盖哪些主题？当然，这意味着其他一切都超出范围，应该推给其他人的文档。
例如，在 Apache Web Server 文档中，我们有一份名为 《入门指南》 的文档，其中涵盖了您在开始之前需要了解的内容。该文档的目标是划定一条界限，说明什么是文档范围之外的内容，同时还将人们指向实际上深入涵盖这些内容的资源。因此，HTTP 规范、DNS 的内部工作原理以及内容问题（例如 HTML 和 CSS）都明确地不在文档范围之内，但每个使用 Apache Web Server 的人都需要了解这些内容。
文档类型
一旦您确定了范围以及您要为谁写作，您可以为他们编写几种不同类型的文档。Anne Gentle 将它们分类如下
从这里开始
就像我之前提到的《入门指南》文档一样，这是您告诉用户在他们甚至开始之前需要了解什么的地方。
参考指南
参考指南是全面的，通常非常枯燥。在这里定义术语，解释函数的输入和输出，并给出示例。语气是事实性和切中要害的。没有太多讨论或对话。声音通常是非个人的。
教程
教程手把手地引导您前进。它们向您展示每个步骤，偶尔会在路径旁的长椅上坐下来解释特定步骤的理由。它们非常健谈，有时甚至很健谈。声音是个人化的；您是在与早期人物角色阶段定义的特定人说话。
学习/理解
学习/理解文档通常从教程链接过来，它们会更深入地挖掘。它们调查特定事物的为什么和如何。为什么做出某个决定？它如何在代码中实现？这件事的未来会怎样？您如何帮助创造那个未来？这些文档有时最好以博客文章的形式完成，而不是作为正式文档的一部分，因为它们可能会严重分散那些只想解决问题的人的注意力。
食谱/配方
食谱 通常是 O'Reilly 技术图书目录中最畅销的部分，这是有原因的。人们想要解决方案，而且他们现在就想要。您的文档的食谱或配方部分应提供针对常见问题的剪切粘贴的最佳实践解决方案。它们应该附带解释，但您应该理解，大多数食谱用户会剪切并粘贴解决方案，这对他们来说就结束了。
您的很大一部分受众只关心解决他们眼前的问题，因为这是他们获得报酬所做的一切，您需要理解这是一个完全合法的需求。当您组装新的宜家桌子时，您不关心为什么选择了特定的螺丝尺寸，您只想要说明书，并且您希望它们能够工作。
因此，示例经过测试至关重要。无论示例多么微不足道，您都必须对其进行测试，并确保它能完成预期的工作。许多令人沮丧的时间都花在了试图弄清楚为什么文档中的示例不起作用上，而几分钟的测试就会发现冒号应该是一个分号。
配方也应提倡最佳实践，而不仅仅是最简单或最快的解决方案。永远不要告诉他们如何不去做，因为他们只会剪切并粘贴那个，然后陷入比他们开始时更糟糕的境地。
我最喜欢的网站之一是 There, I Fixed It，它展示了人们在解决问题时的独创性，而没有过多考虑其解决方案可能造成的后果——他们只是想解决问题。
错误消息
是的，错误消息也是文档。有用的错误消息实际上指向解决方案，可以节省无数的搜索和挫败时间。
考虑以下两条错误消息
`ERROR. FORBIDDEN`
和
`Access forbidden by file permissions. (ERRNO 03425)`
第一个消息令人震惊，但毫无帮助，需要大量摸索才能弄清楚为什么被禁止。第二个消息告诉您这与文件权限有关，并且还具有错误编号的额外好处，您可以在 Google 上搜索到许多详细介绍如何解决该问题的文章。
理念
这种想法完全来自于多年忍受技术支持渠道——IRC、电子邮件、正式文档、Usenet 等等。我们这些掌握答案的人，似乎想让新人感到困难。毕竟，我们以前光着脚在雪地里上学，然后又走回来，记得吗？我们通过阅读代码和实验来弄清楚如何使事物工作。我们为什么要让这些孩子们更容易呢？他们应该被迫挣得它，就像我们一样，对吧？
技术世界每天都变得越来越复杂。您应该知道的事情清单一直在增长，没有人可以成为所有方面的专家。期望每个人都做完功课并提出聪明的问题不仅不合理，而且变得不可能。
富有同情心的技术支持——以及更好的文档——是人们有效使用您的软件的唯一途径。而且，如果他们无法在合理的时间内获得答案，他们将使用另一个具有更好入门通道的解决方案。
在他的 《Programming Perl》（Perl 编程） 第一版书中，Perl 编程语言的创建者和该社区的缔造者 Larry Wall 开玩笑地谈到了程序员的三种美德：懒惰、急躁和傲慢
对这个笑话的解释 非常值得一读，但请记住，这些是程序员作为程序员，与计算机相关的角色中的美德。在 1999 年出版的 《Open Sources: Voices from the Open Source Revolution》（开源：来自开源革命的声音） 一书中，Larry 解释说，作为一个人，与他人交往时，我们应该渴望的三种美德是：勤奋、耐心和谦逊。
当我们帮助人们解决技术问题时，急躁会被视为傲慢。“我的时间比您的问题更重要。” 傲慢被视为贬低。“您的想法很愚蠢。” 懒惰呢？嗯，那只是懒惰。
耐心和友善，帮助人们按照自己的节奏前进（即使感觉很慢），会被视为尊重。欢迎人们来到任何级别，并耐心地帮助他们提升到下一个级别，这就是您构建社区的方式。
不要让人感到愚蠢：这必须是一个核心目标。
即使世界上其他人都很混蛋，您也不必如此。
菜肴
本文是 Rikki Endsley 协调的“Doc Dish”专栏的一部分。要为本专栏投稿，请提交您的故事想法或通过 open@opensource.com 联系我们。
24 条评论