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

图片来源：

原始照片由 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 标签或单独的 FAQ 页面就可以了。
路线图： 制定你未来的愿景和计划以及大致的时间表将使用户长期保持兴趣和动力。你的项目现在可能并不完美，但你有一个完善它的计划。“路线图”部分也是让你的社区参与进来以建立强大生态系统的好地方，因此请确保你有一个链接告诉人们如何表达他们对路线图的想法和意见。（我将在未来撰写关于社区建设的具体细节。）

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

最后一点：包含一个关于你正在使用的许可证的清晰的单句声明（可能在“入门指南”、README 或其他高度可见的地方）。这个小小的举动将使最终用户方面对你的项目进行审查以进行采用更加高效。