GitHub Wiki 是一种反模式

每隔半年左右，总会有人问“GitHub 上到底该用 wiki 还是 docs 文件夹？”这个问题。按照 Shawn Wang 的 three strikes 规则（同一问题被问到第三次就该写下来），我觉得是时候把想法整理成文字了。

本文初稿的开头是“GitHub 项目既可以用 wiki，也可以用 docs 文件夹，两者都是合理的选择”。但随着写下去，我发现用 wiki 的理由只有一个，而不用 wiki 的理由却多得多——多到我直接认定在 GitHub 上使用 wiki 是一种反模式。

先说说用 wiki 的好处：

1. 在仓库的任何页面，一键就能进入 wiki 内容
2. 没有了。

确实，我能想到的用 wiki 的唯一好处，就是它一直待在那里。

那不用 wiki 的理由呢？

1. 使用 /docs 文件夹时，文档和代码一起做版本管理，需要回看旧版本时找起来很方便
2. 别人 clone 仓库时拿不到 wiki（虽然 wiki 可以单独 clone，但这是个隐藏功能）
3. 文档修改和代码一样走完整流程，通过 pull request 获得同行评审
4. 可以用 GitHub Actions 配合 Vale 之类的工具对文档做 lint
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` 文件夹是投入产出比最高的选择。不过随着文档规模超出单个文件夹的承载能力，情况就会变得不确定。你很可能需要一个独立仓库，配备专属的构建流程、Pull Request 审查规范以及其他众多配套机制。届时用户已习惯在仓库中处理文档，因此将 `/docs` 迁移至独立仓库对贡献者来说应当是平滑过渡的。

无论你是否认同上述观点，都欢迎在[Twitter](https://twitter.com/mheap/)上分享你的看法