打造卓越文档的 5 个步骤

来自 Katacoda 和 Ocelot Uproar 的 Ben Hall 在 OSCON 2017 大会 上就另一个我非常关心的话题：文档！发表了精彩的演讲。这是他对演讲的总结。

文档之旅比您想象的开始得更早，从您网站的首页就开始了。用户在阅读您的任何指南之前，会先查看您的网站或 GitHub，以及您在那里发布的示例和演示。

我们在软件方面常犯的一个错误是，我们经常先给人们产品下载，然后让他们访问整个手册，中间没有任何步骤。相反，我们应该以递增的步骤来编写文档，以建立用户的信心。

每个人都非常忙碌和压力巨大，但是当他们来到您的项目网站时，他们有动力解决问题或改进某些东西，您不希望用您的文档（或缺乏文档）来增加额外的压力并让他们失去动力。

这就是为什么几乎每个入门级计算机科学课程都教授“Hello World”示例的原因。它入门门槛低，而且易于人们学习。我们希望我们的文档能够让人们达到一个水平，使他们有信心获取更多知识。

将文档视为以下步骤

1. 探索
2. 入门
3. 引导
4. 指导和发现
5. 参考

步骤 1：探索

想象一下，有人刚刚登陆您的 GitHub 页面，并且他们有兴趣了解更多信息。您在那里有什么可以吸引他们并让他们感到舒适的东西？您的 GitHub 页面是您文档的第一步，您需要快速轻松地回答用户关于“我为什么要关心？”的问题，以便您可以进一步吸引他们。

Ben 分享了这些网站的示例，这些网站在这方面做得很好

• Kubernetes 的网站一开始就非常清晰。
• Project Calico 用一句话解释了它的用途，就在页面的顶部。
• Kotlin 是一个关于如何在下载产品之前让人们对产品感到自信的例子。

步骤 2：入门

现在您已经让您的潜在客户关心您的项目，接下来您需要向他们展示您的产品正是他们解决问题所需的。您大约有九分钟的时间，否则您将失去积极用户的兴趣。

Stripe 是吸引用户的绝佳示例。它有一个非常清晰的“入门”部分，其中包含代码片段。它还包括小的、离散的部分，易于理解和遵循。

步骤 3：引导

用户现在想要使用您的产品。您需要让他们轻松启动并运行。

Mixpanel 是一个很好的例子。它将文档嵌入到门户中，并且没有您必须阅读的长篇文本。它使流程对用户更具吸引力。

您希望帮助人们克服看到系统运行的第一个障碍，因此请直接进入流程。

阶段 4：指导和发现

现在您已经让您的用户设置并运行了，他们可能对您的产品还可以为他们解决哪些其他问题感兴趣。他们已经完成了困难的部分——他们入门了，系统正在运行，现在他们想知道还有什么可能。

Twilio 的网站是这方面的一个很好的例子。您可以从其方便的标题中轻松选择最适合您的文档。它提供屏幕截图、视频、文本内容以及下一步去哪里。

此阶段是开始推广您的社区的好地方。包括探索您社区的选项，并展示人们正在使用您的产品做什么。

阶段 5：参考

现在您的用户想要成为专家，因此他们将寻找您的深入文档。

鉴于这些步骤，谁创建的文档最好？

乐高！乐高拥有所有文档中最好的文档。想想看，他们在文档中不需要用文字解释任何内容；全部都是图片。他们不仅帮助您遵守规则，还鼓励您发挥创造力。他们有一个 Lego ideas 网站，他们在那里让人们发布自己的作品。这让社区感到更加热情。

如果您是软件制造商，您认为哪些是与用户进行文档交互的最佳方式？而且，如果您是用户，您认为哪种文档最有用或最有帮助？