The GitHub wiki is an anti-pattern (2022)(michaelheap.com) |
The GitHub wiki is an anti-pattern (2022)(michaelheap.com) |
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.
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.
Docs being updated to reflect the code can then (and must, IMO) be a blocking constraint on all pull requests.
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.
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.
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.
Really? I feel like most of the stuff I have read advocating monorepos are from people at Google, which is a HUGE 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.
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
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.
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.
Apparently it can even do CI stuff. Still wouldn't recommend it though, for the other reasons outlined in TFA and this thread.
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.
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.
You can even do live edits on the web if you don't want to use a command line.
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."
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.
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.
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.
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.
however I think maybe this has changed? I don't see it in https://github.com/robots.txt now
in repo (can be wiki format):
- dev docs
- user manual
different repo:
- community usage wiki
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.
Google also is very much in the yell loudly and ignore anyone who points out the problems of a monorepo.
In other words, spiritually not a wiki.