This is a fairly naive take. Versioned docs are indeed fantastic. They make all the difference when using a specific version of a program or API that’s changed over time. However, Wikis are not just docs. They frequently contain general information on use of the software, and ‘recipes’ that aren’t specific to a particular version. This includes info that was not known at the time of a release, or has been clarified or corrected with hindsight. Wikis encourage people to contribute this information because it’s quick and easy.
To achieve fully version-controlled docs, and be able to make corrections and additions to any past version, every change would have to be a PR, assesed for which version it first applied to, then patched into that historical release. So is one then forced into organising their repo to use branches for versions? One shouldn’t move tags or rebase, so does it get cherry-picked onto every relevant version? What about when the docs change is relevant to past versions that are still used, but refers to something that didn’t exist or wasn’t possible at the time that past version was released? It’s a far more arduous proposition than a single wiki edit.
GitHub is an anti-pattern, use codeberg
Hmm, good points. Looking at it now, it feels like a feature that only makes sense for proprietary projects, where you want to document specific customer use-cases (which don’t make much sense to version with your code), and where you have project owners that are scared of Git.
I really can’t think of many use-cases for open-source projects. Even if it doesn’t have to be versioned, you would still check it in via Git, because that’s just where your project lives.
I mean, I do know open-source projects with a MediaWiki instance, such as DCSS, but the entire point of those is to allow contributions from random users, not just the devs. And I assume, that’s not how the GitHub Wiki feature works (never actually seen any project use it, though, so I might be wrong).
Docs generated from code, like doxygen and pydoc are pretty good too. Make it part of the normal build process and artifact publishing process.
