Execution Environment Content Strategy

# Execution Environment Content Strategy This document pulls from the [EE epic](https://github.com/ansible-community/community-team/issues/230) to improve the state of EEs in community. Since many items are discussed across different issues in different repository, this document will attempt to bring all the pieces together in one place where we can decide how to go forward on the upstream docs for EEs. ## Problem statement Execution environments remain an under-utilized tool for Ansible users and collection maintainers. The tool itself has been difficult to use, and the resulting EEs can be used in multiple other projects (navigator, runner, AWX, CI integration). We currently have no documentation home for cross-project documentation. ## Areas that need improvement The following areas need to be addressed by this solution. * educating collection owners on EES * how to set ee requirements in their collection metadata * how to use EEs in their collection CI workflow to test agains multiple versions of ansible-core etc ## Areas where EEs are documented The following locations have some level of EE documentation. Most have not been updated to the simplified builderv3 format. * [builder](https://ansible-builder.readthedocs.io/en/stable/) * [runner](https://ansible.readthedocs.io/projects/runner/en/stable/execution_environments/) * [awx](https://github.com/ansible/awx/blob/devel/docs/execution_environments.md) * [navigator](https://ansible.readthedocs.io/projects/navigator/) (in subcommands for builder and in FAQ) * [Ansible SDK](https://ansible-sdk.readthedocs.io/en/latest/intro.html#local-execution) While not directly related, EEs are also mentioned in the following downstream (aka customer-focused) docmentation: * [ansible-controller](https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html and [reference](https://docs.ansible.com/automation-controller/latest/html/userguide/ee_reference.html)) * [EE creator guide](https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/2.3/html/creating_and_consuming_execution_environments/index) * [EE tutorial for RH developers](https://developers.redhat.com/articles/2023/05/08/how-create-execution-environments-using-ansible-builder) * [migrating venvs to EEs for AAP](https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/2.3/html/red_hat_ansible_automation_platform_upgrade_and_migration_guide/upgrading-to-ees) * [Downstream navigator guide](https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/2.3/html/ansible_navigator_creator_guide/assembly-review-ee-navigator_ansible-navigator) ## Identified gaps and problems * EEs are not mentioned in the collection developer documentation at all and should be. * navigator upstream guide doesn't show how to use navigator with EEs or how to verify your EE with navigator * No one place to go to for all info about EEs. Today it's scattered amongst all the docs listed above. * General overview of EEs and why a user or collection maintainer might be interested * how to use EEs, specifically: * persona-based set of user stories/use cases that EEs solve * The GitOps part mainly, every project using EE is reinventing how to build and publish the container. * What should be included in a EE, only runtimes or also tools used to tests your playbooks/collection? * How to version the EE, to me it seems you have to put the EE inside the same GIT repo as the playbooks/collection using it. # Proposed solution Create a How-To/scenario guide for EEs. This guide would be unversioned, but list the versions of each project used when testing the procedures listed in the guide. It should: * Identify user stories/use cases that are real-world. These will use one or more of the projects related to EEs (navigator, awx, etc) * Use navigator and ansible-build introspect to test any EEs built as part of the use case. * Move existing use cases/scenarios from the individual projects up to this new guide where appropriate * De-duplicate information across all the upstream places where EEs are currently document and add links from there up to this new guide. * Publish the guide to `docs.ansible.com/howto/EE_guide` or some similar location. * Source the rst files from `ansible-community/howto-docs` or some similar repository for unversioned guides.