如何为你的开源项目编写有效的文档

图片来源

原始照片由 Marco Tedaldi 拍摄。由 Rikki Endsley 修改。 CC BY-SA 2.0。

不幸的是，好的代码不会自己说话。即使是设计最优雅、编写最精良的代码库，解决了世界上最紧迫的问题，也不会自行被采用。你，作为开源创建者，需要为你的代码发声，并为你的创造注入活力。这就是技术写作和文档编写的用武之地。

一个项目的文档获得的流量最多，远远超过其他部分。人们在这里决定是继续了解你的项目还是放弃。因此，花时间和精力在文档和技术写作上，专注于最重要的部分“入门指南”，将对你项目的吸引力产生奇效。

对你们中的许多人来说，写作可能会感到不舒服，甚至令人生畏。作为工程师，我们受到的训练更多是编写代码，而不是关于代码的写作。许多人还以英语为第二甚至第三语言，可能会对用英语写作感到不安全或害怕。（我学习英语作为第二语言，我的母语是普通话，所以我感同身受。）

但我们无法回避这样一个现实，如果你希望你的项目具有广泛的全球影响力，英语是你必须使用的语言。不要害怕。我写这篇文章时考虑到了这些挑战。你不需要成为下一个莎士比亚才能发现这里的建议有用。

五个可操作的写作技巧

这里有五个可操作的写作技巧，你可以立即应用。它们可能看起来非常简单和显而易见，但在技术写作中却一次又一次地被忽略。

使用 主动语态：主动语态：“你可以通过……更改这些配置” vs. 被动语态：“这些配置可以通过……更改”
使用简单、简短的句子： 虽然不是开源的，但 Hemingway App 和 Grammarly 都是有用的工具。
格式化以便于阅读： 使用标题、项目符号和链接将信息分解成块，而不是长篇解释性段落。
保持视觉化： 使用表格和图表，而不是句子，来表示具有多个维度的信息。
注意拼写和语法： 始终、始终、始终进行拼写检查以查找错别字，并进行语法检查以使其更完善。

通过在你的写作和编辑工作流程中始终如一地应用这些技巧，你将实现两个宏伟目标：高效沟通和建立信任。

高效沟通： 工程师不希望在文档中阅读冗长、曲折的段落（他们有小说可以读）。他们希望尽可能高效地获取技术信息或说明（当它是指南时）。因此，你的写作需要简洁且有用。（话虽如此，在你的项目中加入一些幽默、表情符号和“花絮”来赋予其个性和使其更令人难忘是可以的。具体如何做到这一点将取决于你的个性。）
建立信任： 你必须积累的最有价值的货币，尤其是在项目建设的早期阶段，是信任。信任不仅来自你的代码质量，还来自描述你的代码的写作质量。因此，请像对待你的代码一样，对你的写作进行同样的润色。这是上面第 5 点（关于拼写和语法检查）的主要原因。

从入门指南文档开始

将这些基本技巧融入你的写作后，你应该在文档中花费最多时间的部分是入门指南部分。这是迄今为止最重要的部分，也是“80/20 法则”在行动中的经典示例。你项目的大部分网络流量都落在你的文档上，而其中的大部分都落在入门指南上。如果它结构良好，你将立即获得新用户。如果不是，访问者将跳出并可能永远不会回来。

你如何构建一个好的入门指南部分？我提出以下三步流程

使其成为一项任务： 有效的入门指南应该是面向任务的——一个开发人员可以完成的离散的迷你项目。它应该不包含太多关于架构设计、核心概念和其他更高级别的信息。一个单独的、可视化的架构概述是可以的，但不要用多个段落来描述你的项目是如何以及为什么是最佳设计的解决方案。这些信息属于其他地方（下面会详细介绍）。相反，入门指南部分主要应该是一个步骤和命令列表，以……好吧，开始你的项目！
可以在 30 分钟内完成： 这里的核心要点是完成时间应尽可能短；30 分钟是上限。此时间限制还假设用户对你的项目了解甚少。记住这一点很重要。大多数费心阅读你的入门指南的人都是技术受众的成员，他们对你的项目有模糊的了解，但仅此而已。他们来这里是为了在决定花费更多时间深入研究之前尝试一些东西。“完成时间”是你应该衡量的指标，以不断改进你的入门指南。
做一些有意义的事情： “有意义”的含义取决于开源项目。重要的是认真思考那是什么，将其紧密地定义为一项任务，并允许完成你的入门指南的开发人员完成该有意义的任务。这项有意义的任务必须直接说明你项目的价值；否则，它会让开发人员感觉他们只是浪费了时间。

灵感来源：如果你是一个分布式数据库项目，那么“有意义”可能意味着在你杀死一些节点后，整个集群仍然可用，且没有停机时间。如果你是一个数据分析或商业智能工具，那么“有意义”可能意味着在加载一些数据后快速生成一个具有不同可视化的仪表板。无论“有意义”对你的项目意味着什么，它都应该是可以在笔记本电脑上快速且本地实现的。

一个很好的例子是 Linkerd 的入门指南。Linkerd 是 Kubernetes 的开源服务网格。我是 Kubernetes 的新手，对服务网格的熟悉程度就更低了。然而，我在我的笔记本电脑上完成了 Linkerd 的入门指南，没有太多麻烦，这次体验让我体验到了操作服务网格的全部内容。

上面的三步流程可能是设计高效入门指南部分的有用框架，并且可以以可衡量的方式进行。当涉及到将你的开源项目产品化时，它也与价值实现时间指标相关。

其他核心组件

除了仔细校准和优化你的入门指南之外，还有五个其他顶级组件对于构建完整的文档是必要的：架构设计、生产环境使用指南、用例、参考资料和路线图。

架构设计： 这是对你项目架构的深入探讨，以及你的设计决策背后的理由，充满了你在入门指南中战略性地忽略的细节。本节是你整体产品营销计划的重要组成部分。本节通常充满视觉效果和图纸，旨在将一位普通的业余爱好者转变为一位专家级爱好者，他们有兴趣长期投资你的项目。
生产环境使用指南： 在笔记本电脑上尝试某些东西与在生产环境中部署它之间存在天壤之别。指导想要更认真地使用你的项目的用户是重要的下一步。展示生产环境操作知识也是你吸引最初的商业客户的方式，他们可能喜欢这项技术的前景，但不知道或不确信在生产环境中使用它。
用例： 社会证明的价值是显而易见的，因此列出你的生产环境采用者非常重要。这里的关键是确保这些信息易于查找。它很可能成为入门指南之后第二个最受欢迎的链接。
参考资料： 本节详细解释了该项目，并允许用户在显微镜下检查和理解它。它还充当字典，人们在需要时查找信息。一些开源创建者花费了大量时间在这里详细说明他们项目的每个细微差别和边缘情况。动机是可以理解的，但在你的时间有限的初期是不必要的。在细节和获得帮助的方式之间达到平衡更有效：指向你的社区论坛、Stack Overflow 标签或单独的常见问题解答页面的链接就足够了。
路线图： 用粗略的时间表规划你的未来愿景和计划将使用户保持兴趣并长期受到激励。你的项目现在可能并不完美，但你有一个完善它的计划。路线图部分也是让你的社区参与进来以建立强大生态系统的好地方，因此请确保你有一个链接告诉人们如何表达他们对路线图的想法和意见。（我将在未来撰写关于社区建设的具体细节。）

你可能还没有完全充实所有这些组件，并且某些部分可能会晚于其他部分实现，尤其是用例。但是，要有意识地随着时间的推移构建这些组件。假设你的用户在入门指南方面有良好的体验，那么解决这五个要素是他们进入你的项目的关键下一步。

最后一点说明：包含一句清晰的声明，说明你正在使用的许可证（可能在入门指南、README 或其他显眼的位置）。这个小小的举动将使最终用户更高效地审查你的项目以进行采用。