GitHub wiki 是一种反模式（2022）

原文 ↗ Hacker News 讨论 ↗

许多开发者认为，与把文档保存在主仓库中的 `/docs` 目录相比，GitHub 内置 wiki 是一种“反模式”。他们指出，wiki 位于一个独立且隐藏的仓库中，没有标准的代码审查工作流，可能与代码不同步，也更难被自动化和搜索引擎使用，而且它通常并不是真正意义上的 wiki，因为一般默认不允许公开编辑。也有人认为，wiki 确实降低了通过浏览器快速编辑和记录临时笔记的门槛，但主流观点仍更倾向于仓库内文档，项目变大时尤其如此，甚至会将其生成完整文档站点。

GitHub wiki 与 /docs 的总体立场

  • 许多人认为，与 /docs 目录相比，GitHub wiki 是一种“反模式”。
  • 主要批评：用户体验笨拙、是一个独立且隐藏的仓库而没有常规工具支持、缺乏“真正 wiki”的一些特性（例如默认不可公开编辑、结构受限如缺少目录）。
  • 也有人认为它有价值：适合低门槛、基于浏览器的编辑、临时记录，以及与开发文档分开的社区 wiki。

易用性与工作流

  • /docs 被认为投入成本大致相当，但与以下内容集成得更好：
    • 代码审查和 PR 工作流。
    • GitHub Pages 和静态站点生成器（如 Sphinx 等）。
    • 本地克隆和离线访问。
  • 一些人强调 wiki 的便利性：
    • 一键访问和侧边栏导航。
    • 无需配置任何东西；“就在那里”。
    • 对不想处理 git、PR 和 CI 的非技术贡献者更友好。

版本控制与和代码的耦合

  • 强烈支持把文档放在同一个仓库中，这样代码和文档可以原子性更新。
  • 独立 wiki 仓库意味着：
    • 文档版本不会自动与代码版本绑定。
    • 编辑可能会在未被注意到的情况下“腐坏”，因为它们绕过了 PR。
  • 反方观点：wiki 仍然是 git 仓库，所以版本控制依然存在；可以通过标签、子模块或自动化来管理耦合（例如用 GitHub Actions 将 /docs → wiki 同步，或把 wiki 做成子模块）。

摩擦、审查与贡献

  • 一派观点：文档应该像代码一样经过相同的审查流程，以确保正确性和可见性。
  • 另一派观点：对平凡的文档改动施加审查/CI 要求会带来过多摩擦，以至于文档根本不会被更新。
  • 建议的缓解方式：
    • 对仅修改 markdown 的变更放宽合并门槛或 CI。
    • 将“仅文档更新可跳过审查/CI”作为流程规则，而不是强制工具限制。
    • 使用基于网页的单文件编辑和自动创建的 PR 来降低摩擦。

搜索、索引以及 AI/代理

  • 有人担心 GitHub wiki 的索引程度较低，或受限于一些限制（例如 star 数、默认不可公开编辑），使其更难通过搜索或 AI 被发现。
  • /docs 中的文档被认为更容易被搜索稳定发现，也更容易让代理将其与代码变更关联起来。

替代工具与仓库结构

  • Fossil 被引用为一个例子：其中 wiki 和树内文档都是一等公民、统一且版本管理良好。
  • 有些人总是在项目根目录初始化 src/ 和 docs/，以保持代码和文档并置。
  • 还有关于 monorepo 与 multi-repo 的旁支讨论：共识是二者都有严重的扩展性权衡；对于小项目，单一仓库（包含文档）通常最简单。