###### tags: `Documentation` # Separating the Ansible docsite This proposal examines the possibility of moving RST source content in the `docs/docsite` directory from `ansible/ansible` to another repository. ## Why? RST source content and other assets for Ansible core documentation + Ansible collections documentation currently resides in the `ansible/ansible/tree/devel/docs/docsite` repository. The Ansible community team plans to open up docsite development and tooling. This requires access to compute resources capable of handling large jobs such as the sphinx build target for the Ansible package docs. CI workflows for Ansible community docs should run on ephemeral vms that reduce maintenance and avoid security holes in operations. Using Ansible core CI provides ephemeral vms for commity doc operations. However it necessitates a separate project to isolate Ansible core CI from Ansible community docs CI. In essence this proposal is more focused on separating operations for Ansible core from Ansible community docs than it is about the RST source. ## What changes? A new repository in the Ansible organization that holds the contents of the `docs/docsite` directory. Package docs build adds a step to fetch a specific Ansible core ref. ## What does NOT change? No changes to documentation source that is dynamically generated from the `ansible/ansible` code source. ## Benefits for Ansible community - Allows the Ansible community to take more direct ownership of the docsite development and operations. - Removes Ansible core freeze dates as merge blockers. - Allows us to 'version' Ansible package docs independent of core. Today we are tied to the branching strategy of core. - Allows us to create unversioned documentation (for the contributor guides, which aren't tied to a release). - Allows space for more hackathons and other events that result in bursts of activity. ## Benefits for Ansible core - No longer the gate for docs backports and community operations. - Reduces the number of people who need commit access on `ansible/ansible`. - Eliminates the need for the old Jenkins instance. ## Disadvantages // Issues - Potentically creates a silo for the documentation. - More fragmentation that adds effort to adding/maintaining docs. Developers need to create separate PRs for corresponding docs. - Potentially reduces the appeal of doing easy fix doc issues given contributions are not in `ansible/ansible`. - Confusion in community. Need to announce well in advance and then spend time redirecting contributors who still expect to find RST in `docs/docsite`. ## Risks The proposal to split the docsite must take into consideration that the quality of community docs will degrade over time if it becomes too disconnected from the Ansible core codebase. Among the criteria for measuring docs quality there are two specific concerns: 1. Technical accuracy 2. Completeness To ensure the integrity of these two criteria, the Ansible core team should always remain the authoritative voices of the technical content. The reality is, though, that this risk exists today. The Ansible core team mainly leave doc PRs alone unless specifically requested for review. For the new repository we could create a "core-team-review" group that includes members of the Ansible core team. We could also create a PR label to identify when core team review is required. That would then be the only gate for the core team in terms of docs.