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.
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.
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.
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.
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 where people started calling things "wikis" even though they exemplify the the very thing that the wiki was invented to solve. GitHub's reckless debasing of language has infected adjacent spaces. Sourcehut's "read-only wikis" (wat) can't even 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.
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.
Biggest thing for me is wiki edits skip code review, so docs rot silently while a /docs PR at least shows up in the diff next to the change.
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.
im having trouble connecting the dots here. How does adding the friction of code review reduce rot?
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.
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.
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 where people started calling things "wikis" even though they exemplify the the very thing that the wiki was invented to solve. GitHub's reckless debasing of language has infected adjacent spaces. Sourcehut's "read-only wikis" (wat) can't even 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.
You can set up automation and/or configuration such that changes to the docs folder don't require code review.
That could be easily be corrected by relaxing merge gates for changes only to the `docs` folder (or some suitable naming pattern).
You can even do live edits on the web if you don't want to use a command line.
i was going to say the biggest reason wasn't mentioned here, that github sets Disallow: /*/wiki*
however I think maybe this has changed? I don't see it in https://github.com/robots.txt now
They're not indexed if they're publicly editable
also the repo needs 500+ stars https://docs.github.com/en/communities/documenting-your-proj...
It's likely also better that agents seeing versioned /docs can understand the context of changes to the codebase better.
nit: ”Using the /docs folder is the highest effort-to-reward ratio option” shouldn’t it be lowest or reward-to-effort instead?