关于在吉特哈布（GitHub）上该用 wiki 还是 docs 文件夹的讨论大约每6个月出现一次，遵循肖恩·王（Shawn Wang）的三振规则，作者决定写点东西。文章初版称两者都是合理选择，但写下去后他意识到用 wiki 只有单一理由，不用的理由却很多，甚至认为在吉特哈布（GitHub）上使用 wiki 是一种反模式。接着他列出用 wiki 的好处，称唯一好处是它总在仓库里一键可达。

关于“在 GitHub 上应该用 wiki 还是 docs 文件夹”的讨论大概每六个月出现一次。按照 Shawn Wang 的三振规则，我决定写点看法。我原本想说两者都合理，但写下去发现用 wiki 只有一个理由，不用的理由却很多，以至于认为在 GitHub 用 wiki 是一种反模式。

wiki 的好处： 1. 在仓库任意位置一键就能进 wiki 2. 没有第二条

其实唯一好处就是它一直都在。

不用 wiki 的理由： 1. 用 /docs 文件夹时文档与代码一起版本化，查旧版文档方便 2. 克隆仓库时本地没有文档（wiki 可单独克隆但是隐藏功能） 3. 文档修改走 PR 流程，有完整评审 4. 可用 GitHub Actions 如 Vale 检查文档 5. 能用熟悉工具（如带拼写检查的 vscode） 6. wiki 定制有限，长得都差不多 7. wiki 不能传图，图得放别处

决定文档随代码放后，怎么让人易查看？ 1. 文档放仓库 /docs 文件夹，别用 gh-pages 分支以免妨碍版本化 2. 设 GitHub Pages 发布 * 新手建议 just-the-docs 主题让 GitHub 自动发布 * 想自建（如 Hugo）可用相应 GitHub Action 发布 3. 加一个 wiki 页指向托管文档

新产品用 /docs 文件夹最划算。文档超出单文件夹后可能要独立仓库，但贡献者已习惯在仓库里处理文档，迁移无感。

讨论总体倾向于把 GitHub wiki 视为反模式，理由集中在编辑绕过审查、内容搜不到、功能半成品；但分歧主轴在于：为了降低写文档的门槛，是否值得牺牲版本控制和评审。

认为 wiki 编辑绕过代码审查，是文档悄悄腐烂的根源

• wiki 的改动不进 code review，文档会在无人察觉的情况下过时；而 /docs 的 PR 会出现在代码 diff 旁边（高赞） > 文档编辑跳过评审，于是文档悄悄腐烂，而 /docs 的 PR 至少会和改动一起出现在 diff 里（@hn1rig3rak）
• 每次改 wiki 都不留痕，想靠多开 issue 来管理 wiki 也不可行（较多人）

认为 wiki 的价值恰恰是零门槛，改文档不该走完整流程

• 改个错别字也要 PR、评审和 CI，实际上把文档贡献者限制在熟悉编辑器和 git 的人里（较多人）
• 浏览器和手机上就能直接编辑，这点微小摩擦足以让人干脆不写文档；写文档这件事必须毫无痛感才会真的发生（较多人）
• 真正改进「如何搭开发环境」这类文档的，往往是第二个来搭环境的人，改动跟代码无关，所以更要让改文档无摩擦（较多人） > 让文档更新快到不能再快、容易到不能再容易，比强迫它走完整的软件流程有价值得多（@mikeocool）
• 搭 /docs 本身也要花功夫，wiki 天生就在那里；这类便利已经被 Mintlify 之类的产品做成了生意（少数人）

认为文档与代码同仓同版本，反而更好维护

• 版本化的 /docs 能让代码改动的上下文更清楚，对阅读仓库的自动化代理尤其有利（较多人）
• 文章断言文档长大后必然要拆到独立仓库，这一前提被质疑：把源码、测试和文档放在同一棵树里能让改动更局部，对到处复制同一说明的编码代理也有抑制作用（少数人） > 为什么这被当成理所当然？把文档和代码一起放进版本控制，到了某个规模就真的那么难吗？（@gwking）

认为别的平台已经证明 wiki 与版本控制可以共存

• GitLab 和 Forgejo 的 wiki 本身就是独立的 git 仓库，天然有版本历史；Fossil 更进一步，把文件形式的文档和专门的 wiki 命名空间双向版本化，克隆一次就带走全部内容，两种文档的渲染和浏览方式还完全一致（较多人）

认为 wiki 更适合当草稿本，而不是正式文档

• 有人新开的 wiki 并不用来写文档，而是当公共草稿本，记录还不够明确、不值得开 issue 的想法和实验（少数人）
• 文档应分类看待：仓库内的开发文档和用户手册，与另一处的社区使用 wiki，本来就不是一回事（少数人）

认为 GitHub 的次要功能普遍是半成品

• Issues 和 Discussions 高度重叠，用户两边都会提需求和缺陷，维护者又多一样要盯的东西；Discussions 更像是忽略用户的手段，所以索性关掉（较多人）
• wiki 连目录层级都没有，很难组织内容，更无法并行维护多个大版本（少数人）

认为 wiki 的另一大硬伤是搜不到

• wiki 内容长期不被搜索引擎索引，有人专门做代理站点才勉强可用；也有评论指出 GitHub 的 robots.txt 曾明确禁止抓取 wiki，现在似乎已经放宽（较多人）

有价值的补充

• GitHub wiki 背后其实是一个隐藏的独立仓库，在仓库地址后加 .wiki 就能克隆，理论上也能接 CI，但发帖人依然不推荐（@sigvef）
• 有人指出原文论证结构混乱：把「用 wiki 的坏处」和「不用 wiki 的坏处」混在同一段里，读者得自己推断，这削弱了说服力（@spider-mario）
• 一处措辞纠正：说 /docs「投入产出比最高」写反了，应该是「投入产出比最低」或「产出投入比最高」（@knose）
• markdown 文档在 GitHub 上本来就渲染好了，额外生成站点的动机通常是还要发布到别处，而不是为了让仓库里能读（@ghusto）
• 有人借「写作即思考」评价原文：作者写着写着，开头的「两种选择都合理」就变成了「用 wiki 是反模式」（@a4isms）
• 当天 GitHub 又发生故障、CI 被卡住，有人调侃正好可以趁等待去读 wiki——这条基本代表了对 GitHub 附加功能的兴致（@esafak）