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.
|Foreman Manual||Corresponding docs.theforeman.org entry||Comments?|
|4.1.1 LDAP Authentication||Using LDAP||Review and merge?|
|4.1.2 Roles and Permissions||Managing Users and Roles||Review and merge?|
|4.1.3 Trends||Monitoring Trends||Review and merge?|
|4.1.4 Auditing||Maintaining Foreman Server||Definite gap here in the procedures that should be added to docs.theforeman.org|
|4.1.5 Searching||Searching and Bookmarking||Review and merge?|
|4.1.6 User Management||User Management||This section seems poorly described in the manual|
|4.2 Managing Puppet||no such guide||Needs migrating although sections are scattered throughout different docs.theforeman.org guides|
|4.3 Smart Proxies||Installing Smart Proxy on Red Hat||I would think this needs a separate review. The Smart Proxy docs vs Smart Proxy/Katello docs as is seem to cause confusion.|
|Provisioning||Provisioning Guide||I think we can review for safety’s sake, but drop this section in favour of the docs.theforeman.org content|
|4.5 Command Line Interface||There is a Satellite Hammer guide we can grab if we think it is useful||We can use a script to generate most of this guide|
|4.6 Email Management||5.1.6. Email Notifications||This is buried in new docs, need to raise the heading level|
|4.7 Managing Ansible||Configuring Foreman to Use Ansible||Replace link|
|4.8 Managing Chef||no equivalent to link to||Chef docs will need to be migrated|
|4.9 Managing Salt||No equivalent to link to||Salt docs will need to be migrated|
|4.10 Monitoring||this seems to be monitoring hosts, no equivalent||Will this need to be updated for Host Details page work?|
|4.11 Reports||Using Report Templates to Monitor Hosts||Review & merge|
|5.1API||no equivalent but there is a Satellite API guide we could take||We could also add this to Planning guide|
|5.2 Compute Resources||Comprehensive coverage per Compute resource in Provisioning Guide||Review & Merge|
|Install location Missing Content?||no idea what this should be|
|5.4 Securing Communications with SSL||Configuring Smart Proxy with SSL||No idea if this is enough. Would appreciate any guidance|
|5.5 Backup, Recovery and Migration||Backing up Foreman server & Smart Proxy, Restoring Foreman server or Smart Proxy from a Backup,||I don’t see any migration although Foreman Manual has. docs.theforeman.org has this. All these probably need Foreman-only versions.|
|5.6 Rails Console||no equivalent||need to migrate|
|# 5.7 External Authentication||Configuring External Authentication||Review and merge?|
|5.8 Multiple Foreman instances||no equivalent||Need to migrate|
|5.9 HTTP(S) Proxy||Using an HTTP Smart Proxy||Review & Merge|
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.