on behalf of Red Hat Satellite documentation team and involved Foreman engineers, I would like to show you preview of our effort to bring Satellite documentation sources, git and workflow to public. The ultimate goal is to move all Satellite guides to github and start working on Foreman documentation together with engineering and the community to improve both quality and quantity of the content.
What we have today is the Provisioning Guide, all text is updated to match upstream naming conventions and deployment. What’s still missing are images (diagrams) and broken links to other guides becuase they don’t exist. Other than that, the content is ready to be consumed by users and ready for patches from you guys. See the preview here:
As you can see, structure of the documentation is very different from what we currently have. Instead separate documentation of individual plugins, the content follows individual topics, provisioning in this case. There are various chapters which are only relevant when a plugin is installed (e.g. Discovery, Katello, Remote Execution) and reader is informed about it with links on how to install additional plugins. We believe this is better than individual documentation plugin by plugin. Technically it’s possible to also generate plugin documentation separately, the long-term goal is to futher break chapters down into smaller pieces (modules) and assembly more artifacts (guides, books, pages).
What’s also different is format of the documentation, in order to allow smooth transition from internal Red Hat documentation team git and processes, we adopted their format which is AsciiDoc. We believe it’s also superior to markdown which works the best for short README document but it lacks many very much needed features. Feel free to take a quick look or send us a patch:
What you find in the git repository:
- Source code for the Provisioning Guide in asciidoc format
- Makefile to generate html, pdf and perform link checking
- Short README with more information on how to write and handle upstream vs downstream
- Travis job that verifies html/pdf build and performs link checking
We need your help:
- Incorporating what’s in our current documentation but lacking in the new one.
- Re-drawing diagrams or pictures in some hacker-friendly way so we can easily modify and regenerate them (dot, graphviz or similar)
- Helping to “upstreamize” another guide.
- Preparing a nice “template” with CSS for final presentation.
Next steps. We are going to pick another guide from Satellite documentation book set and “upstreamize” it in the same manner. We have chosen Provisioning Guide as the first one because in our current Foreman documentation we have pretty much zero coverage on this topic. However for other guides we will be also incorporating everything we have currently into the guides so if we choose to promote the new documentation officially, there are no gaps or nothing is lost in the process.
Also, we would like to ask Foreman infra team to help us setting up new domain
docs.theforeman.org, virtual host and pipeline job that would build and push from
master and stable branches into subdirectories like
/1.24. During the transition period, we plan to have a warning banner informing the user that it’s a WIP version of the documentation.