渗透步骤 文档_获得出色文档的5个步骤

渗透步骤 文档

来自Katacoda的Ben Hall和Ocelot Uproar 在OSCON 2017上做了一个很棒的演讲，主题是我心中亲爱的另一个话题。 这是他的演讲摘要。

在您的网站首页上，文档之旅始于您想象的旅程。 在阅读任何指南之前，用户会先查看您的网站或GitHub，以及您经常在其中发布的示例和演示。

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

每个人都非常忙碌和压力很大，但是当他们来到您的项目站点时，他们会被激励去解决问题或改善某些事情，并且您不想增加额外的压力并通过文档（或缺乏文档）来减轻他们的压力。

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

按照以下步骤考虑文档：

1. 勘探
2. 入门
3. 入职
4. 指导与发现
5. 参考

步骤1：探索

假设有人刚登陆您的GitHub页面，并且他们有兴趣了解更多信息。 您在那里有什么可以钩住它们并使它们感到舒适？ 您的GitHub页面是文档的第一步，您想快速轻松地回答用户有关“我为什么要关心？”的问题。 这样您就可以将它们拉远。

Ben分享了这些网站的例子，这些网站做得很好：

• Kubernetes的站点非常清晰。
• 在页面顶部， Calico项目仅用一行说明其目的。
• Kotlin是如何使人们在下载产品之前对产品充满信心的一个示例。

步骤2：开始

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

吸引用户的一个很好的例子是Stripe 。 它有一个非常清晰的“入门”，并附有代码片段。 它还包括易于理解和遵循的小的离散部分。

第三步：入职

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

Mixpanel是一个很好的例子。 它在门户网站中嵌入了文档，并且没有冗长的文本需要阅读。 它使过程吸引用户。

您希望使人们摆脱系统运行中的第一关，因此直接进入流程。

阶段4：指导和发现

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

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

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

阶段5：参考

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

按照这些步骤，谁能最好地创建文档？

乐高！ 乐高拥有最好的文档。 考虑一下，他们不需要在文档中使用文字来解释任何东西； 这是所有图片。 它们不仅帮助您遵守规则，而且还鼓励您发挥创造力。 他们有一个乐高创意网站 ，让人们发布自己的作品。 这使社区感到更加热情。

如果您是软件制造商，那么您认为使用户参与文档编制的最佳方法是什么？ 而且，如果您是用户，那么您认为哪种文档最有用或最有帮助？

翻译自: https://opensource.com/article/17/5/five-steps-documentation

渗透步骤 文档