GitHub Wiki 是一种反模式

# GitHub Wiki 是一种反模式 来源：https://michaelheap.com/github-wiki-is-an-antipattern/ “我应该使用Wiki还是GitHub上的docs文件夹？”（https://twitter.com/joemasilotti/status/1483124554843058180）这类讨论大约每半年就会出现一次。遵循Shawn Wang的“三次机会原则”（https://www.swyx.io/three-strikes/），我觉得是时候就这个话题写点东西了。 本文最初的版本开头写道：“你可以为你的GitHub项目使用Wiki或docs文件夹，这两种选择都是有效的”，但随着内容不断扩展，我意识到使用Wiki的理由只有一个，而不使用Wiki的理由却有很多。理由之多，以至于我认为**在GitHub上使用Wiki是一种反模式**。 先来看看使用Wiki的好处： 1. 你可以从仓库的任何位置，一键访问Wiki内容。 2. 没有第二条了。 真的，我能找到的使用Wiki的唯一好处就是它始终存在。 那么，有哪些理由**不**使用Wiki呢？ 1. 使用`/docs`文件夹时，文档会与代码进行版本控制。如果你需要使用旧版本，文档很容易找到。 2. 当有人克隆你的仓库时，文档在本地是不可用的（你可以单独克隆Wiki，但这是一个隐藏功能）。 3. 文档修改会得到与代码相同的处理。它们通过拉取请求流程获得完整的同行评审。 4. 你可以使用GitHub Actions通过Vale等工具（https://github.com/errata-ai/vale-action）来检查文档。 5. 人们可以使用他们已经熟悉的工具（例如带有拼写检查功能的`vscode`）进行协作。 6. Wiki提供的品牌定制机会有限。它们看起来都差不多。 7. Wiki不支持图片上传，所以你无论如何都得把图片放在其他地方。 现在，你已经认同了将文档与代码放在一起的主意，那么如何让人们方便地查看文档呢？ 1. 将文档添加到你仓库的`/docs`文件夹中。*不要*使用`gh-pages`分支，因为这会阻止文档与代码一起进行版本控制。 2. 设置GitHub Pages构建来发布文档： - 如果你刚开始，我推荐使用`just-the-docs`主题，并让GitHub来构建和发布你的文档。 - 如果你更喜欢构建自己的工作流（例如使用Hugo），你可以使用这个（https://github.com/peaceiris/actions-gh-pages/）GitHub Action来发布文档。 3. 添加一个Wiki页面，指引人们访问托管的文档。 在构建新产品时，使用`/docs`文件夹是投入产出比最高的选择。在某个时候，你的文档会多到一个文件夹装不下，到那时情况就不同了。你会需要一个独立的仓库，拥有自己的构建流程、拉取请求评审指南以及其他一系列东西。到那时，人们已经习惯了在仓库中处理文档，从`/docs`迁移到独立仓库，对贡献者来说应该是无缝的。 无论你同意与否，我很乐意在Twitter（https://twitter.com/mheap/）上听到你的想法。