The GitHub wiki is an anti-pattern (2022)

Original Article ↗ Hacker News Discussion ↗

Many developers argue that GitHub’s built-in wiki feature is an “anti-pattern” compared with keeping documentation in a `/docs` directory within the main repository. They point out that wikis live in a separate, hidden repo without standard code-review workflows, can fall out of sync with code, are harder for automation and search engines to use, and often aren’t true wikis since public editing is typically disabled. Others note that wikis still lower the barrier for quick, browser-based edits and scratchpad-style notes, but the prevailing view favors in-repo docs, sometimes generated into full documentation sites, especially as projects grow.

Overall stance on GitHub wiki vs /docs

  • Many agree the GitHub wiki is an “anti-pattern” compared to a /docs directory.
  • Main criticisms: clunky UX, separate hidden repo without normal tooling, weak “real wiki” properties (not publicly editable by default, limited structure like missing directories).
  • Others see value for low-friction, browser-based edits, scratchpads, and community wikis separate from dev docs.

Ergonomics and workflow

  • /docs is seen as roughly equal effort, but integrates better with:
    • Code review and PR workflows.
    • GitHub Pages and static-site generators (Sphinx, etc.).
    • Local clones and offline access.
  • Some highlight wiki conveniences:
    • One-click access and sidebar navigation.
    • No need to set up anything; “just there”.
    • Easier for non-technical contributors who don’t want to deal with git, PRs, and CI.

Versioning and coupling to code

  • Strong support for keeping docs in the same repo so code and docs can be updated atomically.
  • Separate wiki repo means:
    • No automatic coupling of doc versions to code versions.
    • Edits can “rot” unnoticed since they bypass PRs.
  • Counterpoint: wiki is still a git repo, so versioning exists; coupling can be managed via tags, submodules, or automation (e.g., syncing /docs → wiki with GitHub Actions, or making the wiki a submodule).

Friction, reviews, and contribution

  • One camp: docs should go through the same review process as code to ensure correctness and visibility.
  • Opposing camp: review/CI requirements for trivial doc changes create so much friction that docs never get updated.
  • Suggested mitigations:
    • Relax merge gates or CI for markdown-only changes.
    • Treat “doc-only updates can skip review/CI” as a process rule rather than enforced tooling.
    • Use web-based single-file edits and auto-opened PRs to reduce friction.

Search, indexing, and AI/agents

  • Concerns that GitHub wikis are less indexed or subject to restrictions (e.g., star counts, non-public editability), making them harder to discover via search or AI.
  • Docs in /docs are viewed as more reliably visible to search and easier for agents to correlate with code changes.

Alternative tools and repo structure

  • Fossil is cited as an example where wiki and in-tree docs are first-class, unified, and nicely versioned.
  • Some always initialize projects with src/ and docs/ at the root to keep code and docs co-located.
  • There is side discussion on monorepo vs multi-repo: consensus that both have serious scaling tradeoffs; for small projects, a single repo (with docs included) is usually simplest.