Back in 2019 Red Hat open sourced its Satellite documentation. This talk will answer where it’s today, how it got there and where it can go. All from multiple perspectives, such as end user, (technical) writer and developer.

1. foreman-documentation
rethinking our documentation

2. whoami
●
Ewoud Kohl van Wijngaarden
●
GitHub: ekohl
●
IRC: ewoud
●
Software engineer @ Red Hat

3. Overview
●
Where are we now
●
foreman-documentation
●
Making changes
●
Future improvements

4. Where are we now?

5. A history lesson
●
theforeman.org/manuals created in 2012
– Shortly after Foreman 1.0
●
theforeman.org/plugins created in 2015
●
docs.theforeman.org created in 2019
– Based on Satellite documentation
– Credits to Lukaš Zapletal and Melanie Corr

6. Foreman Manual & Plugins
●
github.com/theforeman/theforeman.org
●
Part of the website, using Jekyll
●
Foreman links to it
●
Large manual + quickstart guide & various plugins
●
/latest and /nightly symlinks using Puppet
●
Branching is painful

9. Introducing foreman-documentation

10. foreman-documentation
●
github.com/theforeman/foreman-documentation
●
AsciiDoc
●
Multiple guides
●
Multiple Flavors
●
Simple web frontend

11. Status
●
Primary source for Katello
●
Experimental for Foreman
– All guides hidden on release branches
●
Upstream
– Red Hat Satellite
– ATIX Orcharhino

14. asciidoc
●
Attributes - like variables
●
Macros & conditionals
●
Easy reuse with includes
●
docs.asciidoctor.org/asciidoc/latest

16. Multiple guides
●
Directory with guides
●
Common
– Attributes
– Assemblies
– Modules
●
github.com/redhat-documentation/modular-docs

17. Multiple flavors
●
foreman-el
●
foreman-deb
●
katello
●
satellite
●
orcharhino

18. Multiple flavors (2)
ifdef::katello,satellite,orcharhino[]
do X
endif::
ifndef::katello,satellite,orcharhino[]
do Y
endif::

19. Collaboration
●
Red Hat & ATIX
– access.redhat.com/documentation/en-us/red_hat_s
atellite
– docs.orcharhino.com
– Weekly sync meeting
●
Writers & developers

20. Pull requests
●
Checks
– Build guides
– Linkchecker
●
Preview with diff

22. Tip to developers:
Use this to review your instructions
Be the user

23. Git structure
●
Git branches
– master – nightly & web
– X.Y – stable branch
●
Simple git branch for new release
●
Cherry picks

24. Future

25. Align on docs.theforeman.org
●
RFC on discourse
●
Clear benefits in a single place
– Clarity of readers
– Less work for maintainers

26. How to get there?
●
Deal with Katelloisms
●
Debian documentation
●
Map all existing documentation
●
Enhance Foreman documentation buttons
●
Update all plugins
●
(Update Red Hat branding mapping)

27. Guides
●
Review existing
●
Further utilize capability of multiple guides
●
Add new guides
– DNS integration guide
– DHCP integration guide
●
Improve landing page
●
Antora?

28. GitHub usage
●
Automate cherry picks
●
Open issue & PR triage

29. Questions?
docs.theforeman.org
github.com/theforeman/foreman-documentation