The code base for Satellite begins upstream and moves downstream. Until recently, the Satellite documentation did not follow the same journey. In this post, I will outline what has been happening with Satellite documentation over the last year and how this benefits both the Foreman community and Red Hat Satellite users.
The Foreman and Katello projects are the upstreams of Red Hat Satellite. The discussions and contributions that take place in the vibrant upstream community help shape the Red Hat Satellite code base. Red Hat’s open source and community strategy has made Red Hat Satellite a robust and flexible product that can manage complex management workflows.
While a team of Red Hat technical writers work on Satellite documentation full time, Foreman and Katello documentation is written by the engineering team and community members who contribute updates and corrections. Because of this, there has been a disparity between the types of documentation that is produced upstream and downstream.
For example, Foreman documentation focuses on features and all possible functions of those features. This documentation is closer in spirit to man pages that describe all things that you can do with a single command. While thorough and accurate, the documentation does not focus on a particular user scenario so it might be hard to use to accomplish certain tasks.
For example the Foreman manual's Roles and Permissions section provides an overview of users and roles in Foreman, but does not delve into the issue of why this information is relevant or walk the user through how to manage users and roles. A similar chapter that is written for the Satellite documentation by a technical writer,Managing Users and Roles provides a set of concepts and procedures that define both the what and then how users can accomplish managing roles and users.
Disadvantages of writing Satellite documentation in the downstream involve duplication of effort. By the time the writing team starts to work on the Satellite feature, the developers who are responsible for the feature have long moved onto another feature in the upstream. To help answer questions about features and use, they then have to dedicate time to switching context back to what is old work for them. The developer has also, to some extent, created documentation in the upstream that may or may not be useful or decipherable by the writing team. However, the biggest disadvantage of documentation not being upstream is the lack of exposure to the community. As with all our open source projects, the more eyes on the documentation and the more bugs raised, the better experience it will be for our customers.
After this situation was articulated, Lukáš Zapletal, Principal Software Engineer for Satellite and Foreman, and Melanie Corr, the Foreman Community Manager, who was Satellite Technical Writer at a time, initiated a process of open-sourcing the Satellite documentation to the upstream Foreman community.
Over the past year, the Satellite documentation team together with enthusiasts from the Foreman community created what Zapletal referred to as Foreman new-generation documentation. This involved migrating Red Hat Satellite guides and adapting them for use both upstream and downstream by working through the following phases:
The writing team and the engineers worked together to put an infrastructure in place that would serve both upstream and downstream documentation. A proof of concept was made and the wider Foreman community was consulted about whether this would be advantageous to them.
The writers worked with Foreman engineers to review guides to identify pieces that are only Satellite-related and therefore must not be displayed for Foreman users.
The team identified terminology that needed to change between the upstream and downstream and used variables to handle this.
Add notes for items that require an additional explanation for Foreman users, for example, that some procedures work only with the Katello plug-in installed.
The writing team collaborated with the wider community to make the Installation guide work for Debian. You can view the result in Installing Foreman on Debian/Ubuntu.
The vast majority of guides are now available in the upstream, but there is still work to be done to consolidate Foreman manuals and ensure that the documentation provides the best possible experience both upstream and downstream. Although the work is still in progress, Foreman community users have provided feedback, for example in Problem with Foreman 2.1rc2 with Remote Execution on CentOS 8:
"The guides on these pages greatly assisted in my understanding of the system…The "Provisioning Guide" was well written, and showed off the [very cool IMHO] hammer CLI interface."
Apart from this main difference in the idea of how to document the product, it is worth mentioning other differences between the traditional and the new documentation:
The new documentation is written in the AsciiDoc syntax, which is more powerful than the traditional Markdown and still is quite user-friendly and easy to write. This syntax also allows for the functionality that makes the new Foreman documentation possible:
The AsciiDoc syntax enables writers to use if statements (ifevals) to make the content visible in only Foreman or Satellite builds.
The AsciiDoc syntax enables writers to reuse the same content in different places. For example, one file is used for the System Requirements section in Installing Foreman on RHEL/CentOS and Installing Smart Proxy on RHEL/CentOS guides to add the same content with slight changes.
The new documentation includes the Foreman + Katello deployment scenario but indicates everywhere that Katello is required.
Even though the new documentation is complete and describes the main common workflows, it lacks some of the Foreman features. These are the features that were not pulled downstream completely, and the new features that did not make their way downstream yet.
The new documentation follows the style guidelines of the IBM Style Guide. Each PR will be reviewed by a technical writer to ensure that those guidelines are met in all content that we add.
From a Foreman perspective, we believe that the new Foreman documentation solves some of the problems around lack of focus on user scenarios of the traditional Foreman manuals and implements a better user experience. As the writing team is working upstream, this also means that future content is reviewed by technical writers and should be of higher quality.
From a Satellite perspective, although we have not fully arrived, we already have pull requests for community members with documentation contributions aimed at the future versions of Satellite. By that time, Satellite documentation will be serving more users than ever before and benefiting from the added interaction and contributions of a passionate base of community members.
I ask you to share your thoughts, comments, concerns, observations, notes about this approach to Foreman documentation. As well as to plant ideas regarding how to progress with this process and make the docs.theforeman.org a unified one stop shop for Foreman documentation. If you are interested, you can contribute to the foreman-documentation GitHub repository.