Michael Heap: GitHub wiki is an anti-pattern for project documentation
Developer argues docs folders beat GitHub's wiki feature for long-term maintainability and contributor workflow.
What to know
- Michael Heap argues GitHub's wiki feature should be avoided for project documentation, citing poor scalability and contributor workflow disadvantages.
- He advocates keeping documentation in a /docs folder within the main repository during development, then migrating to a dedicated docs repository as the project grows.
- The essay frames this as a best practice evolved from recurring six-month discussions in developer communities about documentation strategy.
Michael Heap Developer and technical writer
How it unfolded 1 development · click the chart to see its coverage articlesposts
-
1
“So many in fact, that I consider using the wiki on GitHub is an anti-pattern.”
— Michael Heap -
1 outlet The GitHub wiki is an anti-pattern
first by HN Frontpage, 14h ago
-
> Wikis provide limited branding opportunities. They all look pretty much the same As a docs reader, I'm not sure I'd call that a disadvantage, I agree with the other points though
2 more of the top 3 · 27 posts in this stretch
-
Fossil (https://fossil-scm.org/home/doc/trunk/www/index.wiki) solves this pretty nicely. You can have documentation as files or in a special wiki namespace and it's versioned both ways, and every repository clone gets everything. Even better than that, your in-tree documentation files are rendered and browseable in exactly the same way as the…
-
have you heard of [fossil](fossil-scm.org) ? another distributed versioning system which can im/export from/to git and has integrated: - wiki - issues tracker - forum - chat oh and the special thing about the wiki there is: you can point it to a folder in the project and version your wiki with the same system as your code
-
What people are saying 21 voices from 2 sites · best of 27 · verbatim
- Today
-
> i would have expected being on an "official" github domain directly related to the project would have given you more SEO juice That is, in fact, [the reason they block the indexing](
-
I’ve found the local git side to be part of my workflow and much easier than, ok, where does this wiki do its history, ok go there, then look. Rather than “favorite editor… (or command line) show blame”.
-
Exactly. I’ve tried both, and I much prefer the wiki for most purposes because - I don’t have to go through a whole commit or PR rigamarole to make a minor edit. - The git history doesn’t get cluttered with wiki edits that are irrelevant to the code.
-
In a startup with move-fast lightweight processes:1. Docs that are naturally versioned with the code, like API doc or a design doc, might well go in the code repos. (I'm personally a big fan of API docs embedded in comment chunks right above the respective implementation chunk, but a separate Markdown or SVG file, or other format, also works.)2…
-
that's - kind of surprising to me, lol i would have expected being on an "official" github domain directly related to the project would have given you more SEO juice were it not for the fact that github itself explicitly disallows it
-
I think this person maybe just doesn't understand what wikis are for. > Documentation edits get the same treatment as code. They get a full peer review through the pull request process This is the only mention of edits or access in the whole post. There's an unstated assumption that it would be bad to allow anyone to edit, which, ok, if you think…
-
I disagree, requiring code review for docs changes sounds great but in my experience it's extremely hard to get a human to review docs changes. Either you get a rubber stamp with no real review (zero added value, adds useless friction) or you spend days bugging people to actually review your changes. All for docs!The counter-argument i envision…
-
I expected to see a mention about how [GitHub wikis are, in general, blocked from being search engine indexed](
-
> I find their proclivity to repeat the same idea in multiple locations (agent instructions, docs, docstrings, help strings, comments) especially problematic.I have not taken full advantage yet, but every source sub-directory can have its own CLAUDE.md or AGENTS.md file, with instructions for a given directory, whenever something like Claude opens…
-
One of the benefits of a GitHub wiki is that it is a wiki and can be edited directly without PRs. It's a place for communities to maintain their own documentation, workarounds, and lists of their own relevant projects without having to expend maintainer bandwidth. It's definitely not the place for documentation that needs to be kept up to date by…
-
Weirdo checking inI always initialize my projects with a src, and docs, directory, for exactly this reason.My reasoning is that I shouldn't have to go hunting for the docs for the code, or vice versa.
-
On a large project you will have problems. You can maintain a monorepo anyway as many people do, and deal with the problems of a large monorepo. Or you can go to multirepo and deal with the issues of multirepo. Both have been done successfully, and both have significant problems that you need to work with.Most people advocating a monorepo have…
-
Not many people know that the github wiki is actually backed by a separate "hidden" repo, and can be accessed by adding .wiki to the repo url, e.g. https://github.com/lionleaf/dwitter.wiki.gitApparently it can even do CI stuff. Still wouldn't recommend it though, for the other reasons outlined in TFA and this thread.
-
Another very useful benefit of in-project docs is the ease of `git blame` to see document age.
-
I'm no fan of GitHub add-ons and I agree with the premise here but...I can think of one other possibility. It's easier to write in a wiki via the browser. I can open that on my phone and edit docs. I can open it in my browser and edit docs.On desktop it's a tiny bit more to pull the repo and open it in your editor (and you might already be there)…
-
The last paragraph says: > At some point your docs will outgrow a single folder, and then all bets are off. You’ll want a separate repo with its own build process...My question is, why is this taken as a given? Is it so hard to have docs and code live together in version control after a certain scale? If so, what is the specific problem and what…
-
The second paragraph neatly triggered my confirmation bias:The initial version of this post opened with “You can use the wiki or a docs folder for your GitHub project, both are valid choices” but as I wrote more, I realised that there is a single reason to use a wiki, and many more reasons not to use the wiki. So many in fact, that I consider…
-
In my experience, the docs for something like setting up a dev env are typically greatly improved by the second person who sets up the dev env, not the personal who originally wrote the docs.In that case, when the docs are not associated with a code change, you want to make getting those improvements into the docs as frictionless as possible…
-
> 3. Documentation edits get the same treatment as code. They get a full peer review through the pull request process. Well, that's the main difference, and the key benefit of wikis: they're open for immediate edits and don't require pre-review. YMMV on whether this works for your project or community, some people love it because it enables and…
-
I agree with this post. I’ve never found the GitHub wiki experience to be particularly ergonomic. I don’t have any issues with it, but it’s no more convenient than a simple /docs folder. And from there, it’s almost trivial to turn /docs into GitHub pages. Similar effort for a much better end product.Wikis typically connote distributed, anonymous…
-
Versioning the documentation along with code is a really big thing. It is quite often that I look at a project's guthub wiki, and parts of it are woefully outdated