The GitHub wiki is an anti-pattern (2022)
michaelheap.com
michaelheap.com
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.
Not a big deal if you're basically the only developer and handroll the process - but poly repositories make release and dependency management a lot more straightforward to wrangle
It is unlikely GB/TB is ever a measure, though if your repo is that big and some people only need a subset of the repo it would be.
Managers and others won't touch the repo. (Sometimes it's better the don't...)
Most people advocating a monorepo have never worked on a project large enough to see the issues with a monorepo and so are arguing for a monorepo without understanding the problems with them. For most people a monorepo is the correct answer because their project is small.
By the time you’re “at scale” (who knows), and all these monorepo at scale problems start to overwhelm, you can switch strategy, because the economy of polyrepos is so obvious by then.
So far, I’ve started a new job a handful of times by collapsing a premature polyrepo strategy: people were not experienced enough to merge two git repos without a common root.
I’ve only once went the other way, and it incurred so much overhead, it decreased developer productivity by some small but not insignificant percentage.
To be clear: I’m not a maximalist. All of my open-source work is exceedingly compartmentalised. My DNS library is separate from my external-dns webhook is separate from my fork of external-dns. They could all live in one repo. But FOSS encourages reusability, commercial software encourages clumping and vendoring.
Conversely to your experience, I have worked at a handful of places who have a monorepo that has been creaking under its own weight for years, but its structure as a monorepo now underpins the business, and so migration to a polyrepo simply never happens, and developers are now checking out a 50GB repo in its entirety periodically.
Instead I deal with a 30+ repo clusterfuck (technically we have 60+ services, but I only have to run half...) that is held together by hopes and prayers, takes literal hours of actual effort to bring everything up to date on master, and has become a fractured hellscape where people are afraid to leave their tightly constrained silos of service combinations.
Long story short... I will take a bad monorepo over bad multirepo any day of the week.
It would, of course, be easy to say "But that's not the fault of monorepos! Clearly, 50GB is a nonsensical amount of source code, and clearly someone committed something they shouldn't have in the past."
But also, with monorepos, the probability of that happening to the repo you use the most is the cumulative sum of all of its projects, since more people's potential git mistakes now happen in the same place.
For the sake of comparison, nixpkgs is 4.5GB right now. It hosts ~140.000 packages, ~12.000 open PRs, one million commits, yadda. So when you reach ten times that size with, presumably, less traffic, I would consider cleaning up the history.
Polyrepos can definitely work; I use them extensively in open-source. I also wouldn't be doing that without Nix flakes all over to chain them together. And even then, I have constant drift because one repo is pinning an old version of another repo, and once I bump the pin, things break lazily.
The biggest benefit, by far, you get from monorepos, is eager evaluation of your dependencies.
Really? I feel like most of the stuff I have read advocating monorepos are from people at Google, which is a HUGE monorepo.
Google also is very much in the yell loudly and ignore anyone who points out the problems of a monorepo.
I 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.
edit: I have had one pain point: devs/managers ask me why I do that, and that I stop. I refuse.
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 a file in a folder, if there's an appropriate agent doc in the housing folder, it should read / apply its contents when working. Not sure how this happens with Sub-Agents on that note.
I think if you want both, you might as well add a ./docs/ directory, and put your md documents in there however you want, this has the upside of letting you have docs with your code always, as well as letting you link to direct source code files.
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.
Having said that, there are central hosting projects, but where that has some value with git, git proper is distributed and does not need it but all the auxiliary stuff does. with fossil it provides almost no value. All the auxiliary stuff is built in so all it provides is a place to host. Which is fair but hosting is not hard with fossil.
With everything included in fossil I abuse it as a personal social platform(think discord) super easy to host and it gets me chat, forums, wiki, and file storage. None of them great, but it is so easy I don't really care. voice and video do require an additional service, so there is that. Now I just need to find some friends...
There are only a couple things that I miss:
- Grouping repos together into a combined project. I'd love to be able to have a single Fossil server/instance with a single set of users, wiki pages, tickets, etc. but multiple independent codebases. Closest I've gotten to that is to simply have multiple independent branches instead of a single trunk (example: https://fsl.yellowapple.us/avorion/home), and it's worked surprisingly well, but it's clear Fossil wasn't designed with this workflow in mind, so there are some rough edges with it (albeit minor and easy to work around).
- Compatibility with things that assume you're using Git. Being able to export to Git helps a lot here, but it's still extra steps. Ideal solution here would be for the Fossil server to be able to double as a Git forge and present repos accordingly, such that I can point things like CI/CD pipelines or Terragrunt module calls or whatever directly to the Fossil repo itself over the Git interface those things expect instead of having to setup a Git forge manually and somehow synchronize everything w.r.t. access controls.
- An equivalent to Git's submodules. This would IMO help address the “grouping repos together into a combined project” case as well.
Never wanted to do what you want but it sounds possible
set up the fossil server on a directory of repos probably with --repolist to get a list
fossil server --repolist /var/fossil/
change the menus in each repo to point to the core repo. Based on some quick tests I suspect a full http:// url is required.
- Forum /forum {@2 3 4 5 6}
+ Forum https://mydomain.org/core/forum {@2 3 4 5 6}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, otherwise the changes aren't going to get made.
Personally, I've found that making docs updates incredibly fast + easy to be far more valuable than anything you get from forcing doc changes through the full SDLC process. If someone has feedback on your docs changes they would have shared in a review, they can just update the docs instead.
You can even do live edits on the web if you don't want to use a command line.
In my experience, this is also true of a lot of code as well. Your dev scripts should probably have much more relaxed standards than your service source or CI/CD. Ideally I could define merge requirements by directory without doing some weird shenanigans with the CODEOWNERS file and a bot.
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.
[0]: https://docs.github.com/en/communities/documenting-your-proj...
Wikis typically connote distributed, anonymous edits. This feature is partially covered by git already.
That's because the original sin of GitHub "wikis" is that they weren't (and most of them still aren't) even wikis. There's this perverse thing that happened during the wiki age, where people unable or unwilling to get on board decided to just start calling things "wikis" even though they exemplify the very thing that the wiki was invented as a response to. The reckless debasing of the word then infected adjacent spaces. Sourcehut's "read-only wikis" (wat) aren't even designed to be edited in the browser; on Sourcehut, "Publishing your changes is as easy as committing them and pushing them upstream." Newsflash: That's not a wiki.
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).
But I think the biggest benefit, which we shouldn’t overstate, is that agents will just update docs as they find them. Including for big picture systems. Keeping docs updated is a PITA.
Writing style of AI often sucks. But I’ve found it pretty easy to rectify. And having some correct context is better than nothing or outdated docs in a lot of cases.
Docs do not.
So what results is either allowing developers to push (but not force push) directly to main (you can always push revert commits if needed), or a PR process that exists to enforce linters and build-ability, but if those pass, allow the developer to merge independently, without human review.
Apparently it can even do CI stuff. Still wouldn't recommend it though, for the other reasons outlined in TFA and this thread.
> You can edit wikis directly on GitHub, or you can edit wiki files locally.
https://docs.github.com/en/communities/documenting-your-proj...
> Every wiki provides an easy way to clone its contents down to your computer. Once you've created an initial page on GitHub, you can clone the repository to your computer with the provided URL.
Every GitHub wiki you visit also has a section at the bottom that points to that URL with the description
> Clone this wiki locally
as well.
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 using the wiki on GitHub is an anti-pattern.
A very straightforward example of McCulloch's quote that "Writing is thinking."
An example:
- source: https://github.com/eslint/eslint/blob/main/docs/src/rules/no...
- rendered: https://eslint.org/docs/latest/rules/no-control-regex
This is a very simple example, you can see how the code blocks are highlighted better and slightly interactive.
Exactly, I use Sphinx to make a nice website from the markdown sources (although it doesn't have to be markdown). That includes generating a full API reference page from all the docstrings.
Docs being updated to reflect the code can then (and must, IMO) be a blocking constraint on all pull requests.
https://github.com/super-productivity/super-productivity/blo...
The generic-ness of the wiki wasn't an issue for me as I only intended on using it as a temporary measure to build up the bulk of the content and coordinate with the main dev on finding a balance between the flashy website with its guides and the less flashy docs. gh-pages is the obvious next step of course.
If I were Github I would improve the wiki, a bit stylistically, to make it more visually pleasing to use (but not much, those designers always go overboard when making changes in my experience), but much more importantly so, to make the wiki a more flexible addition, including API-wise, usage examples, documentation and so forth. People can, in principle, do so on their own, but also from experience, most people stop doing so after a while, and then the wiki decays into outdated information. That's bad too. Spawning more issues to manage the wiki also does not work well.
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. Everything else, one of the top priorities is to minimize friction to someone who has the information capturing it such that it can be found by someone else later, so put it in the very low-friction wiki (or an issue/task comment).
3. Have a lightweight way of cross-linking things between these locations, that everyone knows, so info is more likely to be found later.
This still applies even if you feed everything into AI now.
I've been trying for years to get the contents indexed, accessible to search engines or even AI. When I started, no wiki was ever indexed but it seems GitHub backed off a bit since then. Still, there's a bunch that is still not indexed for various reasons with valuable data in them.
I do agree, most users should look into docs instead.
Of course someone will object to doc-only updates not getting review. That person is now on the hook for reviewing all doc updates after you merge them. It's the exact same thing you were doing before - they only objected when it got formalised.
2. Non-technical people can work with tools they know.
3. You may not want to deal with pull, push, merge for every edit.
4. You may not want to deal with PRs for every edit.
5. Setting up `/docs` takes work. Wikis are just there.
Mintlify and others turned this sort of convenience into a business.
in repo (can be wiki format):
- dev docs
- user manual
different repo:
- community usage wiki
however I think maybe this has changed? I don't see it in https://github.com/robots.txt now
In other words, spiritually not a wiki.
and on GitLab: https://docs.gitlab.com/user/project/wiki/
It sounds like the whole argument here is that the commits in the docs repo aren't identical commits in the source code repo. But you can ameliorate that with something like tags or submodules. And it's also inherently true of any project with more than one repo, too.