A developer has made a case that the GitHub wiki is a bad idea, and the argument rests on a single stated advantage: the wiki is always there. The rest of the case is a long list of gripes, most of which boil down to the wiki being a wiki.
The post, titled “The GitHub wiki is an anti-pattern,” draws a simple line. Use the wiki if you want one page that anyone can reach from anywhere in your repository with a single click. Use a docs folder if you want documentation that travels with your code, gets reviewed like code, and stays local when someone clones your project.
One Stated Advantage
The author opens with a concession: there is one benefit to using a wiki. You can get to the wiki contents in a single click from anywhere in the repo. That is the entire case for the wiki’s existence.
The post then lists several reasons against the wiki, including the absence of versioning. Documentation is not versioned alongside your code when using the wiki, which means old versions of the docs are hard to find. That is another reason against the wiki, even though it is framed as a disadvantage rather than a benefit.
Why Versioning Matters
The strongest argument against the wiki is also the simplest. Documentation stored in a /docs folder moves with your code. If you need to use an old version of the software, the docs are easy to find alongside it.
The post also notes that documentation edits get the same treatment as code when they live in the /docs folder. They pass through the pull request process, which means they get a full peer review. That is a real difference from the wiki, where the review process does not exist.
GitHub Actions can lint docs in a /docs folder using tools like Vale. People can work with familiar tooling like vscode with spellcheck. The /docs folder also supports images and custom branding, though the post does not say this directly.
Moving Docs Out of the Wiki
The post offers a clear path for anyone who wants to move away from the wiki. Add your docs to your repository in the /docs folder. Do not use the gh-pages branch, because that prevents docs from being versioned alongside code.
Set up a GitHub Pages build to publish the docs. If you are just getting started, the author recommends using the just-the-docs theme and letting GitHub build and publish your docs automatically. If you prefer to build your own workflow, you can use a GitHub Action to publish the docs.
The final step is simple. Add a single wiki page directing people to the hosted documentation. That way, anyone who clicks the wiki link sees a note pointing them to the real docs.
The Point Where It Breaks
At some point, the docs will outgrow a single folder. Then all bets are off. You will want a separate repo with its own build process, pull request review guidelines, and a whole host of other things.
The post argues that by that point, people are already used to working with docs in a repository. The migration from /docs to its own repo should be seamless for contributors.
The Anti-Pattern Argument
The author considers using the wiki on GitHub an anti-pattern. The post makes this case by listing many more reasons not to use the wiki than reasons to use it.
The wiki fails that test because its benefits are few and its drawbacks pile up. The single-click access is real, but it is outweighed by everything else. The lack of versioning, the missing peer review, the limited branding — these are not minor annoyances. They add up to a system that is harder to maintain and less useful than the alternative.
The post closes by inviting readers to share their thoughts on Twitter.
Key Facts From the Post
- Title: “The GitHub wiki is an anti-pattern”
- Platform: GitHub
- Discussion trigger: Three-strikes rule
- Key claim: Using the wiki is an anti-pattern
The post is a funny kind of honesty. The author builds a whole argument around two actual advantages — one real, one implied — and a list of gripes that mostly come down to the wiki being a wiki. That is funny and honest at once.
The argument is compelling because it is specific. It compares the wiki to a /docs folder side by side, and the differences are stark. The pull request review, the linting, the local availability — these are practical benefits that the wiki simply does not offer.
The migration path is also worth noting. The author treats the move from wiki to /docs as a natural progression, not a disruption. That is a useful framing for anyone considering the switch.
The post is a reminder that the best tool is not always the one that ships with the platform. Sometimes the built-in option is the one that gets in the way. In this case, the wiki is the problem, not the solution.
The author’s three-strikes rule means this argument has been simmering for a while. Now it is written down, and the conversation has moved to Twitter. The docs folder lives on.
Source material: “The GitHub wiki is an anti-pattern (2022),” michaelheap.com.
Get the Notebook.
The day's best stories and every fresh verdict, in plain English, in your inbox by seven. One email a day, no more.