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

图片来源

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

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

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

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

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

五个可操作的写作技巧

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

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

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

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

从入门指南文档开始

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

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

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

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

一个好的例子是 Linkerd 的入门指南。Linkerd 是 Kubernetes 的开源服务网格。我是 Kubernetes 的新手，对服务网格的了解更少。然而，我在我的笔记本电脑上完成了 Linkerd 的入门指南，没有太多麻烦，并且这次体验让我体验到了操作服务网格的意义。

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

其他核心组件

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

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

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

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