Making docs.theforeman.org the primary documentation source

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-deb for Foreman on Debian/Ubuntu
  • foreman-el for Foreman on Enterprise Linux (EL)
  • katello for Foreman + Katello (on EL)
  • satellite for Red Hat Satellite builds (implies Foreman + Katello on RHEL)
  • orcharhino for 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.

9 Likes

I just wanted to praise everyone involved in moving this huge collaborative effort forward step by step. We will be all the better for it!

1 Like

That looks good! I agree with the overall strategy.

There should be a PR hanging with a script that is capable of converting the whole manual to asciidoc with 95% accurrancy.

I’d prefer to avoid converting the manual completely. What I instead of would like is for every file in the nightly manual start adding a link to the new docs location (and possibly replace the content altogether). If there isn’t a replacement, then we should selectively convert. What I mean by that is that various content should be dropped instead.

A more concrete example. If we list the files in the manual and adding mappings we can build a list:

Source EL Replacement Deb Replacement Notes
1.1_architecture.md
1.2_release_notes.md Foreman nightly Release Notes Foreman nightly Release Notes
2_quickstart_guide.md Quickstart Guide for Foreman on RHEL/CentOS Quickstart Guide for Foreman on Debian/Ubuntu
2.1_quickstart_installation.md Same as above Same as above
2.2_quickstart_puppet.md Configuring Hosts Using Puppet Configuring Hosts Using Puppet Not really a quickstart
3.1_system_requirements.md Installing Foreman nightly Server on RHEL/CentOS Installing Foreman nightly Server on Debian/Ubuntu
3.1.1_supported_platforms.md Installing Foreman nightly Server on RHEL/CentOS Installing Foreman nightly Server on Debian/Ubuntu
3.1.2_hardware_requirements.md Installing Foreman nightly Server on RHEL/CentOS Installing Foreman nightly Server on Debian/Ubuntu
3.1.3_puppet_versions.md Installing Foreman nightly Server on RHEL/CentOS Installing Foreman nightly Server on Debian/Ubuntu
3.1.4_browser_compatibility.md Installing Foreman nightly Server on RHEL/CentOS Installing Foreman nightly Server on Debian/Ubuntu
3.1.5_firewall_configuration.md Installing Foreman nightly Server on RHEL/CentOS Installing Foreman nightly Server on Debian/Ubuntu
3.2_foreman_installer.md Needs further review
3.2.1_installation.md Installing Foreman nightly Server on RHEL/CentOS Installing Foreman nightly Server on Debian/Ubuntu I really like show short the current manual is and would like to investigate shortening the new docs
3.2.2_installer_options.md No replacement. Question is if we should replace
3.2.3_installation_scenarios.md Needs further review; Possibly spread out over various documents
3.3_install_from_packages.md Should be dropped from the manual, may stay somewhere else as reference documentation
3.3.1_rpm_packages.md Should be dropped from the manual, may stay somewhere else as reference documentation
3.3.2_debian_packages.md Should be dropped from the manual, may stay somewhere else as reference documentation

This is just a quick look over the first few files, but I hope it gets the idea across.

1 Like

Over a next couple of days I will try to finalize the table of replacements. For now, I only have few:

Source EL Replacement Deb Replacement Notes
3.4_install_from_source.md No Replacement
3.5.1_initial_setup.md Configuring Foreman server Configuring Foreman server Uses foreman-installer instead of foreman-rake db
3.5.2_configuration_options.md References to Admister > Settings throughout the installing guide but no section dedicated to it nor to settings.yaml
3.5.3_database_setup.md No Replacement

How do you feel about shrinking the Foreman Manual until it’s only a list of links for docs.theforeman.org?

I think there’s a lot of duplicate content in there & my proposed way would be to make lots of small commits replacing sections with proper links to Foreman documentation. Options on DHCP/DNS on Smart Proxies and Provisioning Resources come to mind where we definitely do no longer need content from the Foreman Manual.

Some other stuff is IMHO just useless, for example the output of “foreman-installer --help”. I’d rather point users to a) docs for certain workflows or b) a Foreman instance to run that command.

I am a bit unsure on why your tables are so small: is that the only content you’ve identified that’s still missing?

Either way, thanks @ekohl for starting this discussion. I’m really looking forward to having docs.theforeman.org as the only official docs!

That is precisely what I had in mind with the mapping. It is depend on the other steps: we must start showing the content also for released versions, because otherwise we break when Foreman 3.next branches, We’d also prefer to save users from a (manual) redirect, but it is where I’d want to head to. I should have been explicit, but I’m glad you could extrapolate my thinking.

If you’re talking about the previous 2 posts: it’s work in progress. Once we’re done, we should have all files in nightly listed with a plan for each one.

I can move the tables to the initial post. Since it’s a wiki, more people should be able to contribute.

I took another stab at making it possible to link from within Foreman:
https://github.com/theforeman/foreman/pull/9756

I’ve just merged a PR that hides content that’s not ready:

PRs for 3.7 & 3.6 are open:

While it may look like a step back, I see it as a step forward. Because now we can consider guides that are shown as ready.

Next steps would be to review all guides and start making ones that are ready as such. We can also start to expand the navigation with the guides that are ready.

1 Like

Copying from Documentation team meeting 2023-09-18

Orcharhino uses these IDs:

Architectures
ARFReports
Auditing
Bookmarks
Classes
ComputeResources
ConfigurationOptions
CreatingSCAPcontent
EC2
Environments
ExecutingaJob
ExternalAuthentication
FactsandtheENC
foreman_discovery
ForemanRemoteExecution
GettingHelp
GoogleComputeEngineNotes
HTTP(S)Proxy
ImportingRoles
index
InstallationMedia
JobTemplates
LDAPAuthentication
LibvirtNote
Networking
OperatingSystems
ParameterizedClasses
Parameters
PartitionTables
Policydeploymentoptions
Provisioning
ProvisioningTemplates
PuppetReports
Realm
Reports
ReportTemplates
RHEVNotes
RolesandPermissions
SaltVariables
Searching
SmartMatchers
SmartProxies
SmartVariables
Tailoringfiles
UsingComputeProfiles
using-config-groups
Variables
VMwareNotes

And Satellite uses these IDs:

Ansible

ImportingRoles
Variables

Managing Hosts

ForemanRemoteExecution
ExecutingaJob
JobTemplates
ReportTemplates
Reports

Provisioning Hosts

Architectures
Provisioning
InstallationMedia
PartitionTables
ProvisioningTemplates
OperatingSystems
UsingComputeProfiles
ComputeResources
NoVNC
VMwareNotes
RHEVNotes
OpenStackNotes
LibvirtNote
EC2
GoogleComputeEngineNotes
Networking

Puppet Guide

FactsandtheENC
using-config-groups
SmartMatchers
Parameters
Classes
Environments

Administering

ConfigurationOptions
PuppetReports
Mail_Notifications
Realm
Searching
RolesandPermissions
LDAPAuthentication
Bookmarks
Policydeploymentoptions
CreatingSCAPcontent

Planning

SmartProxies
Auditing

Install

HTTP(S)Proxy

Misc

GettingHelp

plugins

foreman_azure
foreman_discovery