tags: Documentation

Ansible community docs 2023: Migrating platform content

This document follows on from the Decoupling core and package docs proposal to focus on Red Hat Ansible Automation Platform content on docs.ansible.com.

Without delving into the historical reasons that lead to the current state, the docs.ansible.com/platform.html page holds documentation for Red Hat customers with Ansible Automation Controller subscriptions.

This results in a silo of content that is confusing for Red Hat customers and out of place within the Ansible community. To break down this silo, there are two basic options:

• Option 1: Integrate Controller docs downstream. Establish conversion workflows that migrate Controller docs into the Red Hat internal publishing system for access.redhat. Over time the Controller docs could be integrated with the rest of the downstream content on but it would require substantial effort from the Red Hat docs team, including ownership and maintenance of the conversion workflows along with content edits and rewrites for style guide adherence.
• Option 2: Identify content in the Controller doc set that is specific to having a Red Hat subscription and do a once-off conversion and handover to the Red Hat docs team. The rest of the Controller doc set becomes the AWX project documentation and joins the Ansible ecosystem on Read The Docs.

Consider that:

• AWX community docs are more internal dev team focused than user focused.
• Constraints on the downstream docs team at Red Hat. Integrating the entire Controller doc set would require significant investments to adhere to RH publishing guidelines.

Option 2 is the best outcome because it means a once-off conversion of a subset of "subscription only" RST to asciidoc, some post-processing tidying up, and a PR to whatever branch the RH docs team designates. After merge TVo can continue what she's doing and publish to Read The Docs

We then port community content from ansible/product-docs to ansible/awx/docs and set AWX up as a docs project in the Ansible ecosystem.

Legacy controller content

Some enterprise customers depend on content at docs.ansible.com/platform for whatever version of Tower or Ansible Automation Platform they are using.

If we lift and shift community content from ansible/product-docs to ansible/awx/docs then we can choose a target release after which no futher additions go into the ansible/product-docs repository. At that point it becomes legacy source that is updated only for certain patches or critical needs.

We should establish a policy for pruning end of life content from the https://docs.ansible.com/automation-tower-prior-versions.html page with a view to eventually remove it.