I would like to start moving our Foreman installation guide from markdown to asciidoc hosted on https://docs.theforeman.org but as the first step, I would like to tackle one particular problem - release notes. I see several problems with the current state:
We currently present release notes as the first chapter in our installation guide: Foreman :: Manual and one of the problems is this is quite lengthy document. While this is definitely important stuff for upgrading, full list of all redmine tickets is quite lengthy and users need to scroll down quite a bit.
Since the list is so lengthy, we tend to keep only release notes for the particular release on the same page, however we know that majority of our users stay on a particular release for some time and then upgrade in batches (e.g. from 1.18 to 2.1). Then they need to switch over from version to version. Not a big deal but worth mentioning.
Finally, our workflow when editing release notes is a bit tricky as multiple people contribute to this and we need to branch off documentation early. People who want to contribute to release notes need to use one branch, people contributing to the manual itself need to make changes in master branch (gh-pages) and the release.
I would like to propose creation of a new document called “Release Notes” with one chapter called Foreman and subchapters for each individual versions. We would link those notes from the current manual, and in the future from the new manual as well. There would be no need to branch off early as master branch would be always “up to date” including all the historical versions. Thanks to dedicated chapters and subchapters, the document would be readable and usable also for users who are planning upgrades over multiple versions.
For release notes for 2.3 I will create a discourse thread (wiki) until we decide if this proposal is good enough and I’d like to start working on this immediately so it’s ready for 2.3. If people don’t like this, I will then fallback to the old workflow branching off early.