As well as the infrastructure, I want to ensure that this does not become a garbage in/garbage out style migration of legacy content. I’d like if everything we publish at docs.theforeman.org is a marked improvement on what we already have. This would make the effort worthwhile.
The original motivation for new documentation/open sourcing of Red Hat docs was that we would have enterprise-quality docs for our open source project, and this is something that I still think is important to maintain.
As part of the effort to move our official documentation to docs.theforeman.org, I’ve been looking at the Foreman Manual.
In my opinion we shouldn’t migrate the Foreman Manual upstream, but stop, look at what is in the manual, and check if the content is already better described in the upstreamised Satellite guides. Where we identify holes, I suggest we enhance what exists in the open-sourced guides. Where we find content completely missing, we add to the new location.
This is my attempt at identifying the above in the current Foreman Manual and I am very much depending on your feedback to steer me. I’m hoping that the various component owners will be able to lend me a hand.
For now, I am excluding the QSG and the Installation parts of the manual. I think the QSG is pretty good. I think the Installation section requires a plan on its own.
I would suggest that Foreman Architecture requires more explanation than is currently available here. The illustration in this section is quite famous, widely used, and beloved by all, so I would not be opposed to transferring it to docs.theforeman.org I’d also be open to a redrawn version!
This is far from where we’d like to be, but it is a start, and perhaps has some useful information for the Foreman/Katello scenario
I also have plans to start a Standard Operating Environment guide this month.
I have made a table of corresponding areas in the Foreman Manual vs docs.theforeman.org. I am making this post a wiki where people can add comments to this table.
I will leave this open for a while, and if there are no objections to my suggestions, I will start removing sections of the Foreman Manual and linking to the docs.theforeman.org.
Where I’ve written “review & merge”, I mean that I will review the section, ensure nothing is missing from docs.theforeman.org, and make changes, then deprecate that section from the Foreman Manual and link to the new area from there. Eventually, we would have a deprecation notice on the Foreman Manual.
In general, I think that troubleshooting guides become a dumping ground. If a topic is well described, you can include the troubleshooting information that relates to that topic at the bottom, or in a specific appendix to a specific scenario.
I wouldn’t be opposed to some form of orderly indexing of troubleshooting information, or advanced information. However, my instinct is that “advanced” information could be added as an appendix to a well described end-to-end scenario in a guide.
I remember having a discussion about including printouts of all the available options, IIRC for the foreman-installer with @ekohl and my main concern is whether or not this will be refreshed and maintained. It would be ideal if we were to create tables or outputs like that, that they would be automated with some script for each new Foreman branch. These quickly go out of date and are rarely maintained manually.
Let me know if you are williing to look at a component that you are familiar with and help me improve the content for docs.theforeman.org
Let me know your opinions about this approach.