GitHub wiki 是一种反模式

“我应该使用 wiki 还是 GitHub 上的文档文件夹？”的讨论大约每 6 个月就会出现一次，遵循 Shawn Wang 的三击规则，我认为是时候写下相关内容了。这篇文章的初始版本以“您可以为 GitHub 项目使用 wiki 或 docs 文件夹，两者都是有效的选择”开头，但随着我写得更多，我意识到使用 wiki 的原因只有一个，不使用 wiki 的原因还有很多。事实上，我认为使用 GitHub 上的 wiki 是一种反模式。让我们从使用 wiki 的好处开始： 您可以从存储库中的任何位置单击一下即可访问 wiki 内容。没有 2。实际上，我发现使用 wiki 的唯一好处是它始终存在。不使用维基的原因又是什么呢？使用 /docs 文件夹时，文档与代码一起进行版本控制。如果您需要使用旧版本，则很容易找到文档 当有人克隆您的存储库时，文档在本地不可用（您可以单独克隆 wiki，但这是一个隐藏功能） 文档编辑得到与代码相同的处理。他们通过拉取请求流程获得完整的同行评审 您可以使用 GitHub Actions 使用 Vale 等工具来检查您的文档 人们可以使用他们已经知道的工具（例如带有拼写检查的 vscode） Wiki 提供有限的品牌机会。它们看起来几乎都一​​样 wiki 不支持图像上传，所以无论如何你都必须将图像放在其他地方 既然你已经接受了将文档与代码放在一起的想法，那么如何让人们轻松查看它们呢？将您的文档添加到 /docs 文件夹中的存储库。不要使用 gh-pages 分支，因为这会阻止文档与代码一起进行版本控制 设置 GitHub 页面构建来发布文档 如果您刚刚开始，我建议使用 just-the-docs 主题并让 GitHub 构建和发布您的文档 如果您更喜欢构建自己的工作流程（例如使用 Hugo），您可以使用此 GitHub Action 来发布文档 添加单个 wiki 页面，引导人们访问托管文档 使用 /docs 文件夹是最高的努力回报当您开发新产品时的比率选项。在某些时候，您的文档将无法满足单个文件夹的需求，然后所有的赌注都会消失。您需要一个单独的存储库，具有自己的构建流程、拉取请求审查指南和一大堆其他内容。那时，人们已经习惯了在存储库中使用文档，并且从 /docs 到其自己的存储库的迁移对于您的贡献者来说应该是无缝的。无论您同意还是不同意，我很想在 Twitter 上听到您的想法