Version Control Documentation


It would be nice to see documentation relevant to a certain a software version. Obviously most people should be using the most recent software but it is confusing when you have something like Where certain software versions have slightly different behavior. This specify cases is fairly understandable but it is messy having warning messages everywhere for legacy software. Documentation should be version controlled just like the software releases.

See ReadTheDocs as an example:
In the lower left corner you can select the software version.

Just a suggestion.


In most firmware updates there is a laundry list of improvements, additions, and corrections in the release notice such as here for example

Hi Daniel

And a very good suggestion it is too! I’m a big fan of Read-the-docs (and Sphinx SSG which underlies it).

Unfortunately we are constrained by the infrastructure (wordpress) which does not easily support this sort of behaviour.

About all you can “easily” is add version metadata so at least people know the version for which the documentation is valid. I was thinking of adding this using tags in the next iteration. You could add version specific documents, but then you run into all sorts of problems with links and search - much easier to sort out with an SSG where each version is a completely separate snapshot.

We could in theory move to this sort of infrastructure, but that creates other barriers for users (I’ve raised this internally as an option, but I do not expect it to be adopted any time soon).

I have created an issue, so you can track any activity done on this: … /issues/36


PS I’ll leave this discussion open for now so we can see if anyone else has any comments. If not, I’ll mark it as closed in the coming weeks.

There was a further suggestion against my last blog that we add versioning information - minimally “last edited” information.

Unfortunately this is not particularly useful on WordPress because I’m making editorial changes to most documents, and these don’t necessarily reflect that the content has been brought “up to date”. A system like MediaWiki allows you to mark changes as “minor edits” but we don’t have that :frowning: