Every few months someone asks whether a project’s docs belong in the GitHub wiki or in a docs folder in the repository. Michael Heap started writing the balanced version of that post and changed his mind halfway through: once he had enumerated the trade-offs, one side had a single entry and the other side had seven.
The case for the wiki:
- It is always one click away, from anywhere in the repo
That is the whole list. Everything else runs the other way:
- Docs in
/docsare versioned with the code, so an old tag still has the documentation that shipped with it; a wiki only has a current state - A clone does not bring the wiki along — it lives in a separate repository that most people never discover
- Wiki edits bypass pull request review, so prose never gets the peer scrutiny code gets
- Docs-as-code composes with tools contributors already have: Vale in CI, the editor’s spellcheck, the diff view people actually read
- Every wiki looks the same, and there is no image upload, so branding and assets end up hosted somewhere else anyway
The replacement he recommends is deliberately boring:
- Put the docs in
/docson the main branch, not ongh-pages— a branch orphaned from main decouples the docs from the code again - Publish them with a GitHub Pages build, using
just-the-docsif the setup should stay trivial - Leave one wiki page that redirects readers to the hosted docs
What makes the argument land is the reframing of the one benefit. “It is always there” is a property of the GitHub UI, not of the documentation, and it is the only thing the wiki offers that the repository does not. That part is also the recoverable part — a redirect page gets it back for free.
The /docs folder is not the end state either. Heap is clear that docs outgrow a single folder eventually, and that the value of starting there is the migration: contributors already expect to review documentation in a pull request, so moving to a dedicated docs repo with its own build and review rules becomes seamless instead of a fight.