# Ansible community doc operations ###### tags: `Documentation` ## Things we want to do / keep doing - Publish core and Ansible package docs on separate release cycles but keep a full docset (aka including core docs) on docs.ansible.com - Publish devel docs on commit and with scheduled nightlies. - Give Ansible community access and visibility to the package docs build. - Support community maintainers with more flexible and open release schedules, merge policies, build hosting, and so on. - Iterate more quickly on content improvement initiatives, like pruning stale docs more frequently. Restructuring the Developer Guide. Removing User Guide stub files. Tackle legacy Galaxy docs. Do an accessibility audit and overhaul content. - Establish consistent and cohesive publishing workflows for Ansible projects. - Kill all the Jenkins jobs. - Reduce legacy AWS infrastructure as much as possible. - Eliminate the need for core PRs to sanity test docs. - Retain Ansible core team technical stewardship for `docs/docsite` content no matter where it resides. Documentation is an engineering function and it is vital that the core team remain the authoritative voice of accuracy and completeness. This goal could be achieved by agreeing on a simple and clear set of review guidelines. - Reduce burden for the core team on things like doc backports and community operations. Note that this goal relates entirely to operations rather than reviewing, approving technical content. - Avoid punching a security hole in infrastructure that allows malicious actors to gain access. ## Split `docs/docsite` from `ansible/ansible` - Core CI // - RTD // - GHA // ## Large hosts on demand - Core CI // Easy but requires an AZP vm with enough capacity. - RTD // Some difficulty as it requires increased limits for build resources included with the business plan: https://docs.readthedocs.io/en/stable/builds.html#build-resources - GHA // Easy but requires larger runner with the GitHub enterprise plan: https://docs.github.com/en/enterprise-cloud@latest/actions/using-github-hosted-runners/using-larger-runners Note that a self-hosted runner has been evaluated for GHA using an EC2 m5.xlarge instance but raises [security concerns](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security) and ongoing administration and maintenance work that isn't sustainable long-term. ## No/low admin burden Can we avoid long-term administration overhead (i.e. keep infrastructure patched and updated)? - Core CI // - RTD // - GHA // ## Keep secrets out of CI workflows Is it possible to avoid adding secrets to CI workflows so arbitrary community contributors can kick off builds? - Core CI // - RTD // - GHA // ## Preview build to stage How easy is it to build preview docs on a staging location? - Core CI // Easy with ephemeral S3 buckets. - RTD // - GHA // ## PR test builds How easy is it to build and test doc PRs? - Core CI // - RTD // - GHA // ## Add linter workflows Can we add linters for spelling and basic grammar plus other syntax like valid yaml? - Core CI // - RTD // - GHA // ## Publish devel on commit Is it possible to automatically update Ansible core docs when a commit is merged to devel? - Core CI // - RTD // - GHA // ## Publish devel nightly Is it possible to automatically update Ansible core and package docs nightly for devel? - Core CI // - RTD // - GHA // ## Removing the AWS web server Can we keep the `docs.ansible.com` domain without the http servers and load balancer? - Core CI // - RTD // - GHA //