api 开源文档编写

不幸的是，好的代码并不能说明一切。 即使是解决世界上最紧迫问题的设计最精美，编写最出色的代码库，也不会自己采用。 开源创建者您需要为您的代码说话，并为您的创作注入生命。 那就是技术写作和文档的来源。

到目前为止，项目文档获得的流量最多。 在这里，人们可以决定是继续学习您的项目还是继续前进。 因此，将时间和精力花在文档和技术写作上，将精力集中在最重要的部分“入门”上，将会为您的项目带来奇迹。

对于许多人来说，写作可能会感到不舒服，甚至令人生畏。 作为工程师，我们比约代码编写更多的训练来编写代码。 许多人也将英语说成第二语言甚至第三语言，并且可能对使用英语写作感到不安全或感到恐惧。 （我以英语作为第二语言学习，母语是普通话，所以我感到您很痛苦。）

但是，如果您希望您的项目具有广泛的全球影响力，那么英语是您必须使用的语言。 不要害怕 我写这篇文章时考虑到了这些挑战。 您无需成为下一个莎士比亚就可以在这里找到有用的建议。

五个可行的写作技巧

这是您今天可以应用的五个可行的写作技巧。 它们看起来非常简单和明显，但在技术写作中却一再被忽略。

1. 使用 主动语音 ：主动语音：“您可以通过…更改这些配置”与被动语音：“可以通过…更改这些配置”
2. 使用简单的简短句子：虽然不是开源的，但Hemingway App和Grammarly都是有用的工具。
3. 易于阅读的格式：使用标题，项目符号和链接将信息分解为大块，而不是较长的说明性段落。
4. 保持可视化：使用表格和图表（而不是句子）来表示具有多个维度的信息。
5. 注意拼写和语法：总是，总是，总是拼写检查拼写错误和语法检查擦亮。

通过在写作和编辑工作流程中始终如一地应用这些技巧，您可以实现两个大目标：有效的沟通和建立信任。

• 高效的交流：工程师不想阅读文档中冗长而曲折的段落（他们为此而拥有新颖的作品）。 他们希望尽可能有效地获取技术信息或说明（当它是指南时）。 因此，您的写作需要精简和有用。 （话虽如此，在这里和那里应用一些幽默，表情符号和“绒毛”是很好的，以使您的项目更具个性并使其更令人难忘。具体取决于您的个性，您做得如何。）
• 建立信任：信任是您必须累积的最有价值的货币，尤其是在构建项目的早期。 信任不仅来自您的代码质量，还来自谈论您的代码的写作质量。 因此，请对您的文字进行与对代码相同的修饰。 这是上面第5点（关于拼写和语法检查）的主要原因。

从入门文档开始

有了这些基本技术，您在文档中应该花费最多时间的部分就是“入门”部分。 到目前为止，这是最重要的部分，也是“ 80/20规则 ”正在发挥作用的经典示例。 大部分的网络流量到你的项目的土地上你的文档，大部分是关于土地的入门。 如果结构合理，您将立即获得新用户。 否则，访客将反弹并且可能永远不会回来。

您如何构建良好的“入门”部分？ 我建议此三步过程：

1. 使其成为一项任务：有效的入门指南应以任务为导向-开发人员可以完成的离散微型项目。 它不应该包含有关建筑设计，核心理念，以及其他更高级别的信息，太多的信息。 单一的可视化架构概述就可以了，但是不要将多段内容专门介绍如何以及为什么您的项目是最佳设计的解决方案。 该信息属于其他地方（在下文中有更多介绍）。 相反，“入门”部分应该主要是步骤和命令的列表，以便……好，开始您的项目！
2. 可以在不到30分钟的时间内完成：这里的核心要点是完成时间应尽可能短； 30分钟是上限。 此时间限制还假设用户对您的项目的了解相对较少。 注意这一点很重要。 大多数不愿阅读《入门指南》的人都是技术受众的成员，他们对您的项目的理解不明确，但仅此而已。 他们决定尝试花费更多的时间进行更深入的研究之前，先尝试一下。 “完成时间”是您应衡量的指标，以不断完善您的入门指南。
3. 做一些有意义的事情： “有意义”的意思取决于开源项目。 重要的是认真思考一下，将其严格定义为任务，并让完成您的入门指南的开发人员可以完成该有意义的任务。 这个有意义的任务必须直接说明您项目的价值； 否则，将使开发人员感到浪费时间。

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

Linkerd的入门指南就是一个很好的例子。 Linkerd是Kubernetes的开源服务网格。 我是Kubernetes的新手，对服务网格还不太熟悉。 但是，我在笔记本电脑上轻松完成了Linkerd的《入门指南》，而且经验使我对操作服务网格的意义有所了解。

上面的三步过程可能是一个有用的框架，可用于以可衡量的方式设计高效的入门部分。 在生产开源项目时，它还与实现价值的时间度量标准相关。

其他核心组成部分

除了仔细地校准和优化《入门》之外，还有五个其他顶级组件对于构建完整的文档是必不可少的：体系结构设计，生产中使用指南，用例，参考和路线图。

• 体系结构设计：这是对项目体系结构和设计决策依据的深入探讨，其中包含您在《入门指南》中战略性掩盖的细节。 这部分是整个产品营销计划的重要组成部分。 本部分通常包含视觉效果和绘图，旨在将休闲爱好者转变为对长期投资于项目感兴趣的专家爱好者。
• 生产中使用指南：在笔记本电脑上尝试某些东西并将其部署到生产环境之间存在很大的差异。 下一步，重要的一步是指导想要更认真地使用您的项目的用户。 展示生产中的操作知识还可以吸引潜在的潜在客户，他们可能喜欢这项技术，但对在生产环境中使用该技术不了解或不自信。
• 用例：社交证明的价值显而易见，因此列出生产中的采用者很重要。 此处的关键是确保易于找到此信息。 它可能是“入门”之后第二受欢迎的链接。
• 参考：本节详细说明了该项目，并允许用户在显微镜下检查和了解它。 它还充当字典，人们在需要时可以查找信息。 一些开源创建者在这里花费了大量的时间来说明他们项目的每个细微差别和边缘情况。 动机是可以理解的，但是当您的时间有限时，这种动机一开始就没有必要。 在详细信息和获得帮助之间取得平衡是更有效的：可以使用指向社区论坛的链接，Stack Overflow标签或单独的FAQ页面。
• 路线图：制定一个粗略的时间表来规划您的未来愿景和计划将使用户长期保持兴趣并受到激励。 您的项目现在可能还不够完善，但是您有一个计划来完善它。 “路线图”部分也是让您的社区参与构建强大生态系统的好地方，因此请确保您有一个链接，该链接告诉人们如何表达他们对路线图的想法和意见。 （我将在以后写有关社区建设的详细信息。）

您可能还没有完全充实所有这些组件，并且某些部分可能会比​​其他部分更晚实现，尤其是用例。 但是，请注意随着时间的推移逐步扩展这些功能。 假设用户在“入门”方面有良好的经验，那么解决这五个要素是用户进入项目的关键的下一步。

最后一点：在您使用的许可证上包含清晰的单句声明（可能在“入门”，“自述”或其他明显可见的地方）。 这种微小的接触将使您的项目审核从最终用户的角度更加有效。

花20％的时间在写作上

这里更细微的一点是，您应该将工作写入正常的工作流程中，因此它成为例行程序，而不是孤立的琐事。 随着时间的推移逐步取得进展，而不是一味地完成所有写作工作，才可以帮助您的项目达到最终目标：吸引力和信任。

特别感谢Cloud Native Computing Foundation的开发倡导者Luc Perkins的宝贵意见。

本文最初出现在 COSS Media上， 并经许可重新发布。

翻译自: https://opensource.com/article/20/3/documentation

api 开源文档编写