使文档成为开源项目优先事项的 5 个技巧

开源软件现在已成为主流；开源项目仅吸引开发人员的时代早已过去。如今，各行各业的用户都是开源软件的活跃消费者，你不能指望每个人仅通过阅读代码就知道如何使用该软件。

即使对于开发人员（包括那些在其他开源项目中有丰富经验的开发人员）而言，当人们加入社区时，良好的文档也是一个有价值的入职工具。 有兴趣为项目做贡献的人通常从编写文档开始，以熟悉项目、社区和社区工作流程。

开源文档的常见挑战

尽管所有人都同意文档很重要并且需要完成，但我们执行文档的一些方式导致项目文档不同部分质量低下且缺乏一致性。 例如，当开发人员过于关注代码时，他们直到最后一刻（例如，在发布之前）才开始编写文档。 而且通常，文档任务由志愿者完成，他们很难说“不”。 更糟糕的是，人们可能会在发布后忘记文档，因此他们永远不会更改或改进它，恶性循环重复。

5 个最佳实践

在过去的几年中，我们参与了 Linux 基金会网络 和 GitLab 的许多开源项目的文档编写。 下面，我们将分享一些我们学到的东西，我们希望这些东西将有助于使文档成为你开源项目中的头等公民。

1. 像重视代码贡献一样重视文档贡献：许多开源社区的重点往往放在代码上。 确保每个人都重视文档贡献的一个简单方法是在你的社区指标中给予文档和代码同等的重视。 提交、合并请求或拉取请求是针对代码还是文档应该无关紧要。 此外，当你进行社区表彰时，请包括文档贡献者的主要成就。

2. 将文档和代码放在同一个项目仓库中：我们强烈建议项目的代码和文档都驻留在同一个存储库中。 （一个好方法是将 /doc 或 /docs 作为存储库中的顶层目录。） 首先，这使任何人都可以轻松找到文档。 更重要的是，当所有内容都在同一个存储库中时，你的文档将与代码和其他项目资源处于同等地位。

3. 将文档作为合并或发布里程碑的要求：如果你的项目发布周期较长（例如，三个月到六个月或更长时间），我们强烈建议为文档设置临时检查点（如 ONAP 社区的这个示例）。 这确保了文档工作不会推迟到发布前，而是每个人在整个发布周期中都致力于文档编写。 如果你的社区可行，你可以将文档作为所有会影响用户的代码贡献的必需步骤（参见 GitLab 的这个示例）。

4. 为代码和文档制定一致的贡献流程：我们还建议为代码和文档制定一致的贡献流程并使用相同的工具链。 正如我们前面提到的，许多新的社区成员通过编写文档开始贡献，因为你通常不需要深入的技术软件知识即可入门。 对于新贡献者来说，通过熟悉贡献工作流程并与其他社区成员会面来加入社区是件好事。 如果这些新贡献者以后想参与项目的其他部分（包括代码），你希望工具链和贡献流程是熟悉的。 否则，他们将需要经历另一个入职流程，这会给贡献者造成不必要的障碍。 如果你的代码和文档有不同的贡献流程，你可能会冒着造成文档不如代码重要的印象的风险。

5. 拥有完善的文档贡献流程：这似乎是显而易见的，但很容易被忽视。 由于文档是新贡献者的良好切入点，因此你希望尽可能降低入门门槛。 拥有关于贡献工作流程、如何入门、在哪里找到要处理的问题、如何获得帮助等的良好文档，将大大有助于新贡献者感到受欢迎并参与到你的社区中。

还有什么？

你是否有其他使文档成为开源社区中头等公民的技巧？ 如果有，请在评论中分享。

本文基于 2020 年 6 月在北美开源峰会上提出的确保文档成为开源项目中的头等公民。