The GitHub wiki is an anti-pattern
The GitHub wiki versus docs folder debate resurfaces every few months. Michael Heap argues that the wiki has only one benefit—it's always there—while versioned docs in a /docs folder offer peer review, local access, linting, and tooling. He recommends using the /docs folder with GitHub Pages, and a single wiki page pointing to the hosted docs.
So many in fact, that I consider using the wiki on GitHub is an anti-pattern.
- ericyd
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 is: "update your docs and code at the same time in the same PR!" That works great, until you want to document something that isn't precisely tied to a single piece of code. In fact I think the most useful docs describe high level systems rather than being associated with specific pieces of code. Use comments for that; in contrast, docs should be easily editable by anyone at all times, otherwise they never get updated (an evergreen problem in any scenario).
- gwking
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 is the cause?
I ask because I've never been that satisfied with the various ways I've tried to organize projects in git. Recently I've been trying to keep the source, tests and docs together in the same tree so that changes are more localized. It seems to be helping me keep track of things, especially with coding agents so eager to make changes all over the place. I find their proclivity to repeat the same idea in multiple locations (agent instructions, docs, docstrings, help strings, comments) especially problematic.
- chungy
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 dedicated wiki namespace.
The linked URL to the home page there can even serve as an example: the "trunk" is a check-in name (https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki) that points to the newest check-in on the "trunk" branch. You can replace it with any other reference to get the old version; eg, version-2.20 would work to get the version 2.20 of the docs, 2015-03-14 would work to get the version from 14 March 2015, etc.
- WCSTombs
I completely agree. When the docs are in the same repository as the source code, at least you can keep the documentation atomically synced to the code. No other method allows this (not counting setups with Git submodules, which is the same thing with more steps), and that should be an immediate dealbreaker.
Docs being updated to reflect the code can then (and must, IMO) be a blocking constraint on all pull requests.
- codazoda
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) but that tiny bit can be enough to stop you from writing documentation. For me, writing documentation must be totally painless so that I'll actually do it.
Why am I not a fan of the add-ons like PR's, wiki's, discussions, projects, and issues? Because they each introduce vendor lock-in to varying degrees.