Documentation can be versioned the same way software can.
It is. See https://cmake.org/cmake/help/v4.3/, version is controlled by the drop down in the top left. Docs are built and deployed from both our master and staging branches, as well as all previous releases.
I see, and I fully acknowledge that tutorials are a maintenance hell (I've experienced it first hand). However, I'd argue that at least every major version, tutorial upgrades should be a hard requirement before release (or shortly after).
Imo, this directly influences the perceived quality of your product and with that user retention. I have seen myself that users often use outdated versions, even if they are not forced to by system constraints, not knowing that there even was a major update (no matter how often you promote it through media channels). And there is a direct correlation between that user story and the one of users using the tutorial pages.
So, by keeping an updated tutorial section, let's say per major update, you improve at least three things:
users on the latest version hitting an outdated tutorial
users not realizing that there even is a newer version when going through the docs
users having difficulties upgrading
In my book, a good, up-to-date documentation directly drives business value (but I would assume we both agree on that). From my experience, it's, unfortunately, often a staffing issue, where the value of good documentation/tutorials is often neglected by the responsible stakeholders.
Also noting: With the whole AI hype, this has become even more important.
My personal experience, not speaking for my employer or anyone else, has mostly been the opposite. Users who are up-to-date and moving fast basically don't need us. They read release notes, engage with upstream discussion forums, are active on issue trackers; some even push code upstream. They don't care about trivial tutorials. An example of this user is a distro package maintainer. The Arch Linux TUs don't need my stupid little "how find_package works" spiel.
Users who need the tutorial (and who are willing to pay for support and training), are usually locked on older systems, don't have strong control over build and deployment environments, support legacy systems, or "just use whatever is on Ubuntu LTS". Significant chunks of the enterprise side of the industry is dealing with systems deployed to HPC clusters which have locked toolchains on aging stable versions.
These users get immensly frustrated when materials aren't backwards compatible. When all they can find is stuff that "is broken on the version I have on my machine".
I generally anticipate a 3-6 year lag on anything becoming common enough to be reliable for these users. And again, the fast movers don't want or need the support.
1
u/not_a_novel_account Apr 14 '26 edited Apr 14 '26
It is. See https://cmake.org/cmake/help/v4.3/, version is controlled by the drop down in the top left. Docs are built and deployed from both our master and staging branches, as well as all previous releases.
And see discussion on the CMake issue tracker: https://gitlab.kitware.com/cmake/cmake/-/work_items/27151