tl;dr: Quoting Make foreman-documentation the primary upstream documentation Milestone · GitHub
Today https://docs.theforeman.org is the primary documentation for Katello, but vanilla Foreman still relies on Index of /manuals. This milestone should be considered done when we can remove redirect all manual pages to https://docs.theforeman.org.
Background
Back in 2019 an effort was started to use the Red Hat Satellite documentation as a base for all our documentation:
Today we can say there is some success. For example:
- Starting Katello 4.0 it is the primary documentation source
- foreman-documentation is the proper upstream for Red Hat Satellite’s documentation, which means that all fixes are delivered upstream first
- There is good (and increasingly better) collaboration. Now writers and developers collaborate
- We hit the milestone where a feature was documented before it was even in a release candidate
We can (and should) be proud of that, but we’re not done yet. It still isn’t the primary documentation source for Foreman without Katello. There was a call for action to convert missing content:
However, there’s also quite a lot of content shown that shouldn’t be. Quite a bit of documentation assumes the presence of Katello, but that’s not always there. We already have some ways of dealing with this. On a technical level we define attributes for 5 build targets:
foreman-debfor Foreman on Debian/Ubuntuforeman-elfor Foreman on Enterprise Linux (EL)katellofor Foreman + Katello (on EL)satellitefor Red Hat Satellite builds (implies Foreman + Katello on RHEL)orcharhinofor ATIX Orcharhino (implies Foreman + Katello on EL)
Then using statements like ifdef::foreman-deb[] or ifndef::foreman-deb[] we can show/hide sections based on the build target. It’s also valid to use multiple targets (ifdef::katello,satellite,orcharhino[]).
Moving forward
Showing only valid content
I’ve opened Make foreman-documentation the primary upstream documentation Milestone · GitHub as a more consistent effort to track the remaining tasks and added some existing issues.
What @lzap already started doing is to hide guides on platforms where we know the guide isn’t ready for consumption we should not render anything.
I’d propose we take a slightly different route: rather than rendering an empty page we show some placeholder describing the status. It may be easier to see an example:
Now for Managing Content it’s a bit of an exception: we’ll probably never have content on a vanilla Foreman. However, there are also other guides which we can deem “not ready”. In that case I’d propose we hide all content describing that it’s not ready for consumption.
Today we don’t link to stable builds for foreman-el and foreman-deb, but once we apply the above I think we should be ready to include the stable releases in our navigation.
Moving over Foreman itself
Foreman can link to documentation. In the UI there is getManualURL(). This is backed by by the LinksController.
This does not support linking to the new generation documentation (which makes me wonder how Katello does this). There was a PR to add this:
This needs to be finished. Once there is an API to link to the new documentation, we should convert all links to the new places.
I’d imagine the first step is to convert everything in Foreman itself. Probably by relying on grep to find instances and then try to map these. Additionally a deprecation message should be emitted if the current manual (or a plugin manual) is linked. Then plugin authors should do the same conversion step as Foreman itself.
Along the way we may find we lack content or something should be converted. Ideally we would at least get an overview of the remaining work.
What may help here is that the Red Hat Satellite branding plugin already contains some of this information we’re looking for.
Last words
I think this outlines a strategy to get to the end state where docs.theforeman.org is the only documentation location. Since it’s a strategy, it’s not concrete. It may even be missing some big steps. I welcome any feedback. Any help with this effort would also be very welcome.