> "Specific revisions should be documented, but documentation should not be limited to a specific revision."
I think this boils down to “what do you do if you realize the documentation for v1.1 says that some feature does X when it actually does Y, but you’re already on version 2.2?”
If v1.1 docs are tied to the version tag in VCS, that incorrect statement cannot be fixed.
And it seems that fixing that forces you into backporting documentation even if you don’t release and maintain parallel versions of your software, which… kinda sucks.
To be honest, I much prefer docs in the repo, because it facilitates code review — a good patch touches some implementation, some tests, and some docs.
The downside when only the latest few versions of the software are supported and only the very latest docs are maintained is that historical docs will probably not be fixed.
> If v1.1 docs are tied to the version tag in VCS, that incorrect statement cannot be fixed.
It can be fixed, just checkout the branch, git cherry-pick the updated change set, or even write it by hand, then do a re-release. You should have a process for this anyway as there might be a critical bug in that code that needs to be fixed and a re-release must happen.
Of course git's handling of branches leave much to be desired (I want mercurial to come back just for it's branch handling) and so developers often forget they can do this and it isn't really that hard. It is tedious though, and you will eventually have dual maintenance where you have to write the same code twice just because the two branches have diverged - this shouldn't be an excuse not to do it though.
I think this boils down to “what do you do if you realize the documentation for v1.1 says that some feature does X when it actually does Y, but you’re already on version 2.2?”
If v1.1 docs are tied to the version tag in VCS, that incorrect statement cannot be fixed.
And it seems that fixing that forces you into backporting documentation even if you don’t release and maintain parallel versions of your software, which… kinda sucks.
To be honest, I much prefer docs in the repo, because it facilitates code review — a good patch touches some implementation, some tests, and some docs.
The downside when only the latest few versions of the software are supported and only the very latest docs are maintained is that historical docs will probably not be fixed.