Michael Heap publishes essay on GitHub wiki documentation anti-pattern
1 Yesterday · 20h ago · 1 article · 3 posts · 4 sources · development 1 of 1
Heap argues that GitHub's wiki feature should be avoided in favor of a /docs folder approach, claiming the wiki's only real benefit is its constant availability while numerous factors argue against using it. He positions /docs as the optimal path during early product development, with migration to a separate documentation repository when needs outgrow a single folder.
“So many in fact, that I consider using the wiki on GitHub is an anti-pattern.”
Michael HeapMichael Heap Developer and technical writer
The whole story articlesposts the bright band is this development · numbered dots are the others · click one to jump
What was reported 1 claim about this development
-
1 outlet The GitHub wiki is an anti-pattern
first by HN Frontpage, 20h ago
What people said 24 voices · best of 28 · verbatim
-
> 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
-
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…
-
> 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…
-
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…
-
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
-
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…
-
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
-
> 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…
-
I expected to see a mention about how [GitHub wikis are, in general, blocked from being search engine indexed](
-
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…
-
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…
-
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…
-
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…
-
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)…
-
Another very useful benefit of in-project docs is the ease of `git blame` to see document age.
-
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…
-
> 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](
-
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…
-
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.
-
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.
-
Yeah I read the article multiple times to see if I was missing anything. No, it just doesn't address this further. I would have appreciated a more detailed breakdown, as the author mentions considering.
-
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…
-
Wikis support this too; it's not an advantage one way or the other.
-
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.
All 1 developments of Michael Heap: GitHub wiki is an anti-pattern for project… →
LobstersHacker NewsMastodonNewswires