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.
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 using the wiki on GitHub is an anti-pattern.
A very straightforward example of McCulloch's quote that "Writing is thinking."
I really wanted the wiki to at minimum have directories so they would be easier to structure and allow even for major versions that are maintained in parallel.
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 edits. This feature is partially covered by git already.
> I’ve never found the GitHub wiki experience to be particularly ergonomic.
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.
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, 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.
Indeed, and also now with agents everywhere the docs can be updated and checked more regularly. If it's in the wiki, you can clone it locally and put an AGENTS.md line informing of where the docs are, but it's still a separate repo to deal with. Credit where due, it was a revolution (even a godsend) in it's time, but at this point I agree a /docs is better.
Interesting because I just added a wiki for one of my projects. I'm not using it for docs, since the project already has in-tree docs. I'm using it more as a public scratchpad of ideas / experiments to try that aren't well-defined enough (or known to be worth) opening as an issue yet.
Yes, and the rest of it is too; there's another outage today and my CI is blocked. I guess I can read the wikis while I wait, eh?? https://www.githubstatus.com/
The Github wiki is pretty bad. However had, it is easier to use than issues and coordinating them. Github issues require too much cross-communication and not everyone has the time to meta-coordinate many different issues in many different projects. A wiki lowers the entry-barrier too, so the idea of a wiki is, in principle, good.
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.
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.
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.
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."
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.
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.
however I think maybe this has changed? I don't see it in https://github.com/robots.txt now
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.