Red Hat, one of the Foreman community members, has made a decision to migrate all Red Hat downstream documentation sources to the DITA XML markup language and its DITA Open Toolkit implementation. (An example of what documentation written in DITA looks like: What Does DITA Look Like? | TechWhirl) This includes Red Hat Satellite documentation, which is currently produced in the AsciiDoc markup language in GitHub - theforeman/foreman-documentation: Documentation for the Foreman Project and its ecosystem, in a shared repository with the Foreman documentation.
Currently, Red Hat writers work in the community repo and then synchronize the documentation to Red Hat’s downstream toolchain. With Red Hat’s downstream documentation toolchain changing, this upstream-to-downstream workflow will be affected. This is why, in the interest of transparency, Red Hat wants to inform the community of the upcoming changes, even if the full scope of the impact might currently not be fully known.
The current expectation is that the Red Hat Satellite documentation team will migrate to DITA next year (2026). Red Hat’s documentation team is already in the process of identifying documentation changes that are needed to enable the migration, such as adjustment to markup, headings, or the existing AsciiDoc file structure. However, the migration will eventually involve more than these cosmetic changes, which is why Red Hat has been investigating questions such as the following:
- Will Red Hat writers continue to be able to work upstream-first after Red Hat migrates to DITA?
- Will Foreman documentation be required to adjust the current workflow and tooling to enable further collaboration with Red Hat writers?
- Will Foreman documentation be required to migrate from AsciiDoc to a different markup language as well? If so, will that different markup language be DITA or something else?
Red Hat welcomes the community’s input. Please let us know if you have any questions, concerns, or ideas.