使开源项目中文档优先的 5 个技巧

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

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

开源文档的常见挑战

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

5 个最佳实践

在过去的几年中，我们参与了 Linux 基金会网络 和 GitLab 的许多开源项目中的文档工作。 下面，我们将分享我们学到的一些经验，希望这些经验能够帮助使文档成为您开源项目中的头等公民。

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

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

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

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

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

还有什么？

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

本文基于 2020 年 6 月在北美开源峰会上提出的“确保文档在开源项目中是一等公民”的演讲。