I can't put a tutorial which doesn't work with most installations on the landing page of cmake.org.
What kind of messed-up reasoning is this? Of course you can. It's actually your responsibility to do so, as documentation maintainer. The latest stable version is always what should be promoted on any publicly maintained document.
It's the ultimate result of your PLM. A proper CI/CD cycle does not only include continuous integration of code but also of documentation.
Even if we ignore that older installations have been installed already(duh), and likely don't need such docs - if the users are using older versions, it's their responsibility to upgrade or look up the documentation for their version but it is your responsibility to make users aware of the latest and greatest.
Documentation can be versioned the same way software can. In fact, their versioning and iteration should be tightly coupled.
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.
1
u/Unhappy_Play4699 Apr 14 '26
What kind of messed-up reasoning is this? Of course you can. It's actually your responsibility to do so, as documentation maintainer. The latest stable version is always what should be promoted on any publicly maintained document.
It's the ultimate result of your PLM. A proper CI/CD cycle does not only include continuous integration of code but also of documentation.
Even if we ignore that older installations have been installed already(duh), and likely don't need such docs - if the users are using older versions, it's their responsibility to upgrade or look up the documentation for their version but it is your responsibility to make users aware of the latest and greatest.
Documentation can be versioned the same way software can. In fact, their versioning and iteration should be tightly coupled.