Github分析400万仓库和访问4万个开发者告诉你开发文档的重要性

接上篇《Github分析400万仓库和访问4万个开发者总结了九条快速代码交付的建议》，本文从开发文档角度展示Github在分析400万仓库和访问4万个开发者之后，得出来的关于项目开发文档重要性的结论。

Github得出的数据显示，在工作中，当文档是最新的（通过查看其时间戳）并且得到其他人的大量支持时，开发者会认为文档是值得信赖的。开源项目使用自述文件、贡献指南和 GitHub 问题来提高项目的质量，并共享信息，使它们对新贡献者更具吸引力。企业可以采用相同的最佳实践来取得类似的成功。

在这开源和工作环境中，当文档是最新的、详细的、可靠的并且采用不同的格式（例如文章、视频、论坛）时，开发人员的生产力提高了大约 50%。

所以对于您的团队来说，是时候查看您的团队使用的文档了：看看最后一次更新是什么时候？您团队中的每个人都可以改进文档吗？经常检查这一点以保持正轨。

Github总结了如下六个方面，针对如何管理文档进行了阐述。

文档对项目开发是不可或缺的

文档通常是项目资源不足的领域，尽管对于新贡献者的入职、提高工作质量和建立共识至关重要。

数据显示：通过不同形式的文档共享和获取知识可提高开源项目和工作中的生产力。内部文档涵盖了入门、管理、教程、结构/依赖关系和最佳编码实践。

使用数据：使用这些图表来确定可以改进工作的一件事！在底部（箭头末端）选择一些东西，然后向后看有什么影响。有关每个构造的更多详细信息，请前往我们使用的调查项目的相关信息。

模型中的每个框都是一个构造（开发工作、文档或健康社区的实践；或做好这些事情的结果）。每条线是构念之间的预测关系。当您看到一行时，您通常可以将其解读为“预测”或“影响”。彩色线为正关系，灰色线为负。对于这个特定部分，模型没有显示任何负面关系（因此，没有灰线）。

给你的代码仓库添加贡献指南吧

当公司与开源社区密切合作时，清楚地理解项目的约定有助于建立彼此的工作。

数据显示：在创建企业级开源软件时，贡献指南已成为“参与规则”。用于开源和工作的存储库拥有贡献指南的可能性是其他存储库的 4.4 倍。

使用数据：如果您还没有贡献指南，请向您的存储库添加贡献指南。这些具有使代码无冲突且易于使用的额外好处。

为什么公司要向其存储库添加贡献指南？当开发人员知道如何为属于不同团队或社区的存储库做出贡献时，它消除了歧义和冲突，他们的工作效率提高了 17%。

是否需要README？

开源存储库通常使用README来共享信息并表示社区活跃。

数据显示：我们的分析发现，工作存储库使用 README 的次数远少于开源项目，但这可能是因为它们在其他内部论坛或方法中共享文档和信息，以及使用配对或入职伙伴进行知识转移。

使用数据：尝试将 README 合并到您的存储库中，以将基本信息与代码保持一致。

GitHub Issues 也是一种文档

共享项目信息的另一种方式是通过 GitHub Issues。

数据显示：创建问题是最常见的第一个贡献，并邀请非代码贡献者。这为人们加入 GitHub 并帮助管理项目提供了一种很好的方式。

使用数据：想想你自己的项目和新的团队成员：人们可以通过轻松地创建问题来参与项目吗？

如何吸引开发者

数据显示：将问题标记为 Good First Issues 是引导新成员做出第一次贡献的好方法。大型存储库通常更可能使用 Good First Issue 标签，这是一种有效的做法。 21% 到 30% 的问题被标记为 Good First Issues 的存储库平均有 13% 的新贡献者。拥有超过 40% 的 Good First Issues 可以帮助项目吸引 21% 以上的新贡献者。