在2016年秋天，我和我的同事被指示改善以前公司的文档和内容。 我们花了一年时间编写各种文档：API参考，指南，教程，博客文章。 在那之前，我写了5年的码头，但我并未正式学习。 但是我不能被称为没有经验的人：除了为项目和初创公司编写API文档之外，我还在大学的最后一门课程学习期间在研讨会上教过Python Flask。 但是现在，这是一个仅专注于我最喜欢的业务的机会：通过技术文档帮助各个级别的专家。

今年，我从Write Docs社区，其他API提供商以及试错方法中学到了很多东西。 去年，我在波特兰API策略和实践会议上的“我想了解有关编写文档的知识”报告中分享了我的经验。 本文是对所学知识的概述。

人们实际上是如何阅读文档的？

“一个国家在一个单一文本的大片段中颤抖”， The Onion摄

您知道图片中的这种感觉吗？ 它发生了。 也许不是身体上的，而是人们很可能在精神上发抖。 我一直以为人们不会阅读我的文字，除非我以一种易于消化的方式将它们读出来，这让我感到不安。 天哪，即使在本文中也可能发生这种情况。

在2006年尼尔森·诺曼小组（Neilson Norman Group） 的一项调查研究中 ，有232位用户查看了数千个网页。 事实证明，用户通常使用F模式查看页面：

1. “首先，他们在水平方向上阅读，通常是在内容区域的上部。 这是图F的顶部元素。”
2. “然后，他们在页面上向下移动一点，然后进行第二次水平移动，通常所覆盖的区域比上一个短。 该附加元素形成图形“ F”的中间元素。
3. 最后，用户垂直扫描内容的左侧。 有时这是一个缓慢而系统的扫描，在热图上显示为实心条。 有时运动会更快，从而在热图上形成斑点。 这是图F中的最后一个垂直元素。”

热图尼尔森·诺曼集团

该研究发现了一些替代扫描模式，例如泡芙蛋糕模式，斑点地图，布局模板，旁路模式和有目的的模式。 我强烈建议您阅读该报告 。

重要的是要注意，F模板妨碍了用户的使用 ，但是内容的正确定位有助于防止F扫描。

该文档有哪些具体含义？

• 前两段应指示最重要的信息。
• 前3-5个字很重要
• 标题，段落和项目符号列表，带有翔实的文字
• 为了保持读者的注意力，可能需要更改字体（大小，链接，粗体等）。

那么如何构造页面上的内容？

• 禁止扫描：确保突出显示读者需要的信息
• 一个段落的想法。 如果有多个，则将该段中断
• 用户会跳过所有看起来像横幅的内容，因此请注意插图。
• 请勿将文本列扩展过多：最好为65–90个字符

我从凯文·伯克（Kevin Burke）的演讲 “如何为不读文档的用户编写文档”中学到了一些技巧。 Kevin在2011年至2014年期间为Twilio文档提供了支持。

此外，各段都有自己的细节。 就像The Onion的文字一样，当您阅读很多段落时，可以跳过要点。 那为什么要经常使用它们呢？ 让我们从Keen IO文档中进行实验：

快速阅读以下内容：

事件集几乎可以使用任何名称，但是有几个规则：名称不得超过64个字符。 它只能包含ASCII字符。 不能为空。

现在快速阅读以下内容：

事件集几乎可以具有任何名称，但是有一些规则：

• 标题不得超过64个字符
• 它只能包含ASCII字符
• 不能为空

在两个示例中，文本完全相同 。 这不是牛顿的二项式：第二种有助于更好更快地吸收信息。 如果该段落包含任何类型的列表，请将其变成项目符号列表。

稍后我们将更详细地讨论文档的布局和导航。

代码示例

没有代码的API文档是什么，对吗？ 我们的许多文档中都有代码示例，而用户实际上已经阅读了它们。 但是问题是，他们并不总是注意周围的文字。

示例代码中的上下文对于开发人员的成功至关重要。 开发人员喜欢快速复制和粘贴。 这是Keen IO API的示例：

var client = new Keen({ projectId: "your_project_id", writeKey: "your_write_key" }); var ticketPurchase = { price: 50.00, user: { id: "020939382", age: 28 }, artist: { id: "19039", name: "Tycho" } } client.addEvent("ticket_purchases", ticketPurchase); 

开发人员快速复制并粘贴此代码。 还有...



首先，他们如何运行文件？ 可能类似于node file_name.js ，但这不在代码中。 可以在顶部的注释中指出。

好吧，他们启动了它，并且... ReferenceError: Keen is not defined 。 :-( Keen客户端未启动，在顶部没有import或require语句，并且仅在安装npm库之后才能工作。

用户修复它，然后再次运行...猜猜！ 另一个错误！ your_project_id和your_write_key丢失。

所有这些都可以变得更加明显。

这是Twilio文档中的一个示例，为最终用户提供了良好的上下文：


Twilio Node Helper库文档的屏​​幕截图

这立即阐明了如何安装该库，将其嵌入到您的代码中以及在运行它之前需要在示例代码中替换哪些内容。

复制粘贴错误

因为我们在文档中有很多示例代码，所以成功的复制粘贴是非常重要的特性。 这是两个不遵守此规定的示例：

 #      $ gem install rails 

看起来很无害，对吗？ 再想一想，将其复制并粘贴到命令行后会发生什么？ 您很可能会收到：

 bash: command not found: $ 

一个常见的错误。 您希望该命令在命令行上看起来像，还是不小心复制了它。 我建议放弃$ 。 您还可以找到一种禁止复制此符号的方法，以使该错误不会使用户烦恼。

最近的例子：您是否检查过突出显示用户要复制的代码有多容易？

Kelsey Hightower难以在Google Cloud Next演示文稿中从StackOverflow复制示例代码。


“优秀的程序员复制，优秀的程序员粘贴”

他是故意这样做的吗？ 我们永远不会知道。 但是，这说明了程序员如何尝试在某些文档站点上突出显示大块文本。 确保网站的用户界面可以轻松复制大块。 您甚至可以分解这些块来分别解释这些片段。 因此，它们将变得更易于复制和理解。

“就这些！”

“就这些！” 这个短语在上下文中看起来似乎是无害的，但可以想象一下，当遇到问题时，如何感觉到诸如“简单”，“简单”，“平凡”和“不复杂”之类的某些单词-不好！ 当一个人试图使API正常工作时，这样的短语会质疑他的智力，并让他问一个问题：“所以我很愚蠢？” 它使人士气低落。

过于简化

简化很常见。 在初学者编写文档时最常见。 通常，文档的作者同时是系统的开发人员，因此对他们来说有些事情“容易”。 但是他们开发了此功能，为其编写了代码，对其进行了很多次检查，然后编写了文档。 当您执行数十次操作时，很显然，这对您来说将是“轻松”的。 但是，以前从未见过UI或功能的人呢？

移情

单词的选择确实很重要。 同理心是理解和分享他人感受的能力。 当我们表现出同情心时，我们不仅可以帮助新手，而且可以帮助更高级的用户。 这有助于增加潜在的用户，用例，客户，甚至公司收入。

但是，当文档是由专业项目开发人员编写的时，同理心就更困难了。 以下是过去对我有帮助的一些有用提示：

• 让经验不足的项目参与者诚实地对文档发表评论。
• 鼓励经验不足的项目参与者贡献或指向他们不了解的文档点。
• 创建鼓励问题的环境，包括对经验丰富的项目参与者似乎“显而易见”的问题-这将帮助您发现“盲点”
• 在代码审查和CI流程中使用代码处理器，以确保所有用户的同理心和语言友好性。
• 最后，要求对真实用户的文档发表评论，向他们显示文字并询问是否一切清晰

错误消息作为一种文档

通常，用户比文档更容易看到错误消息。 根据Kate Voss的说法，“错误消息实际上是一个机会。” 我相信许多文档开发人员会错失良机。 有培训的地方，建立信任关系和用户期望。 首先，您将帮助人们自助。

Kate at Write The Docs提供了许多有关编写错误消息的有用信息。 在之前关于API错误消息的工作中，以及在障碍的另一端，我从开发人员那里收到来自其他API的错误消息，从而学到了很多东西。

凯特（Kate）说，好的错误消息建立在三个原则上：

• 谦虚
• 人性化
• 有用性

谦虚

即使不是您的错，也需要立即道歉。 我也在支持服务中对此进行练习。

一个例子：

抱歉，无法连接到___。 请检查您的网络设置，连接到可用的网络，然后重试。

人性化

使用易于理解的术语；避免使用诸如“呼叫目标抛出异常”之类的短语。 在编写触发了许多错误消息的代码时，很容易掌握清晰的词汇。

示例（Twilio 401状态代码错误）：

 { “code”: 20003, “detail”: “Your AccountSid or AuthToken was incorrect.”, “message”: “Authenticate”, “more_info”: “https://www.twilio.com/docs/errors/20003", “status”: 401 } 

有用性

如果您记住这些技巧之一，请记住有用性。 与用户共享有关如何解决问题的信息。

一个例子：

抱歉，您尝试上传的图片太大。 重试高度小于4000像素，宽度小于4000像素的图像。

如何写错误信息

与其他任何文档一样，请首先提供重要信息。 这可以通过首先指定对象，然后指定操作来完成。 用户正在寻找结果，而不是如何到达那里。 当用户快速扫描错误消息时，此功能很有用。

错误的例子：

按返回按钮返回上一页。

很好的例子：

要返回上一页，请使用“后退”按钮。

文档错误消息

当文档中提到常规API错误消息时，我发现它非常有用。 这样，文档作者可以在不扩大文档范围的情况下澄清错误消息，同时帮助用户理解错误发生的原因。

Twilio发布错误和警告的完整目录，以及可能的原因和解决方案。 使用此方法，可以使实际错误消息更短，但仍然有用。

如果出现错误20003（前面提到的状态码401错误），则在目录中有许多可能的原因已明确列出。


资料来源： https : //www.twilio.com/docs/api/errors

Stripe的功能与各种错误代码的详细描述类似。




资料来源： https : //www.twilio.com/docs/api/errors

您甚至可以在StackOverflow问题中找到错误消息。 谦虚地，人性地和有益地回答他们。 由于使用SEO，用户通常最终会在StackOverflow上看到错误消息，而不是实际的文档。

提示：如果有人没有做出谦虚，人性化和有益的回应，那么只要有足够的“声誉”，您就可以编辑StackOverflow答案。

选词

许多单词都有公认的思维模式。 例如，诸如“库”，SDK，“包装器”和“客户端”之类的单词已经超载，并引起了读者的注意。

Ruthie Bendor在他的演讲“写文档”中的演讲中， “即使是在这个演讲中，也很难找到名字” ，为什么选择正确的单词会如此困难。

我们通常会选择较差的单词，尽管在编写文本时我们总是这样做。 像许多SDK标题一样，每个单词都会引起读者广泛的感觉，想法和定义。 您可能不理解这一点-通常我们会做出错误的假设。

在这种情况下，著名的谚语从未像现在这样正确：“计算机科学领域只有两个困难的任务：缓存无效和发明名称。” 这句话经常归功于Phil Carleton，但是今天这种说法有很多变化。 有时最后他们会添加“ ...以及每单位错误”。 Ruti认为这证明了当今的软件主要基于他人的代码或工作。

为什么保留错误的对象名称（或文档）？

与过分简化一样，我们经常不明白这个名字是不好的。 这就是Ruthie所说的移情失败 。 这就是怎么说不成功的单词的问题与我无关，因此不存在。

美国的提示：为防止意外的种族主义，请使用“禁止使用的清单”和“允许使用的清单”代替“黑色”和“白色”。
（来源： 安德烈·斯塔尔兹 （ Andre Staltz）和rails / rails / issue / 33677 ）

这仍然让我想起了Ruthie所说的新手思维错误 。 这就像在说：“这对我来说是完全清楚的。 我不明白别人怎么会不明白这一点。”

最后，Ruthie提到了本地化错误 。 例如，中文中的Bing一词表示“病”。

根据2017年GitHub开源调查的研究 ：

几乎25％的开发人员读写英语不是“很好”。 在项目中进行交流时，请为非英语国家的人们使用一种易于理解的语言。

在文档中使用美国主义和成语时，您是否考虑到这一点？ 其中许多对于用户而言可能是难以理解的。

提示：我坚信，解决这些问题的最大“诀窍”之一是文档团队的多样性。

在某些情况下，我们承认错误，但是我们不能或不想纠正它，因为我们...

• 绑在她身上
• 我们找不到时间
• 我们看不到重要性
• 我们没有机构来解决它。

您可以说或听到：“但这是我的创意！”，“谁删除了我的甜心？” “如果重命名，一切都会崩溃”，“我不相信更改此名称会影响任何重要的事情。”

在文档方面，您不必担心重构和重写。 如果您不同意最初不是最佳选择的事实，该如何改进呢？

如何选择正确的单词？

首先，我建议您提出一个问题：您的用户使用哪些词？ 不同的程序员圈子使用不同的术语，请勿尝试使用其他术语。 这不仅对读者有用，而且对搜索和SEO也很有用。

最后，一切都不可避免地归结为主观评估。 但是，需要考虑一些原则。 Ruthie说，坏名声可以：

• 尴尬的
• 伤心
• 误导
• 混淆
• 冒犯

另一方面，好名声：

• 有助于突然的澄清（“就这样！”）
• 注入上下文
• 解释
• 照亮
• 提供支持

我建议在扣除文档时考虑这些品质，以便对此进行有益而诚实的审查。

选择正确的单词很困难。 没有魔术公式。 所有用户都不同，产品用例也不同。 对某些人有效的方法可能对其他人无效。 如果简单的话，每个人都会有更好的文档。 正如Ruthie告诉开发人员：“编写程序是发明名称的一种练习。 处理它。” 而且，如果您正在为其他人的程序编写文档，请“告诉开发人员，如果其名称没有达到目标”。