# Making community docs a separate project to ansible/ansible
###### tags: `Documentation`

This document proposes to separate the source content for Ansible community documentation published at `docs.ansible.com/ansible` and `docs.ansible.com/ansible-core` from the `ansible/ansible` repository.

This proposal is intended to benefit the Ansible community by decoupling community doc initiatives from core release cycles. Additionally this proposal removes the Ansible Core team as the gate for other changes that will meet community needs, such as putting source content for `docs.ansible.com` under the direct control of the Steering Committee.

It is a first step towards providing greater access and ownership of `docs.ansible.com` to the Ansible community.

### Problem statement

Source for statically generated HTML that is provided as part of the Ansible package documentation and Ansible core documentation resides in the `ansible/ansible` repository under the `docs/docsite` directory.

Over time having both sets of documentation in the same repository has led to the following problems for the Ansible community:

* Lack of access to community content that is not directly related to core, such as Ansible package installation, porting guides, roadmaps, contributor guides, and so on
* Cannot tag docs to reflect the Ansible package release. Everything in `ansible/ansible` is tagged and branched for core releases, not Ansible package releases.
* No control over documentation releases and publishing, CI workflows and testing, and versioning of build requirements.
* Inability to experiment with building higher-level or unversioned documentation.

### Proposed Solution

The Ansible core team is facilitating a lift and shift of `docs/docsite` from `ansible/ansible` to [`ansible/ansible-documentation`](https://github.com/ansible/ansible-documentation).

Along with the entire contents of `docs/docsite` the lift and shift will include the following:

- `.github/workflows/ci.yaml` actions for RST and docs build tests.
- `docs/bin/clone-core.py` clone relevant portions of ansible-core from ansible/ansible into the current source tree to facilitate building docs.
- `examples/` scripts and files referenced in documentation.
- `hacking/` scripts and tooling for various things related to doc builds.
- `licenses/` open source license files.
- `tests` RST and docs build tests.

This allows community to take over all docs-related work over time and puts community documentation in community hands. Over time, we will separate out the core docs from community docs and move community docs to a github repo that is entirely under communit/Steering Committee control. Take this as the first step to getting us in that direction.

> The `ansible-core` developer team has agreed to maintain technical stewardship over all documentation that relates to the core project (user guides, deve guides, etc). They will continue to review incoming docs issues, create PRs, and provide technical review of docs PRs. They will also commit to adding docs PRs for core features as they are merged into the `ansible/ansible` repo to ensure technical accuracy remains in the ansible docset.

### Testing and feedback timeframe

To ensure community members have time to evaluate and 'test drive' this proposed solution, we have updated the publishing toolchain to build from the [`ansible/ansible-documentation`](https://github.com/ansible/ansible-documentation) starting on Thursday, June 15th.

The testing and feedback timeframe will run for a two-week period, ending June 29th, 2023.

All docs PRs will happen in the new repository during this test period and be published regularly to `devel` docs to see if we come across any technical glitches.

On June 29th, we will end the test period and provide an evaluation to the Ansible community and find agreement on a date to proceed with the lift and shift, which should take place as soon as possible.

If it looks like everything is in place and we're ready to proceed, then **July 10** could be a suitable date for the split. At this point, the `/docs` folder and `/examples` folder [will be deleted from `ansible/ansible`](https://github.com/ansible/ansible/pull/81011).

## Additional outcomes

Because this proposal is intended as an interim solution or a "first step" there is the need to define subsequent outcomes. Other than documentation improvement initiatives, this proposal is designed to achieve the following objectives:

- Allow the Steering Committee to gain full control of source content and resolve [community-topic #240](https://github.com/ansible-community/community-topics/issues/240)
- Evaluate and simplify the content in the `examples/` folder, which contains a good few artefacts that are likely to be no longer be maintained or related to docs. We can easily prune stale content, relocate files to avoid excessive `../../` relative links in `literalincludes` directives, and generally clean it up for less complexity.
- Evaluate and improve the `hacking/` folder, which will be temporarily duplicated with the `ansible/ansible` repository. This folder contains quite a few artefacts not relevant to docs but is included in its entirety to make sure the `ansible-documentation` repository has a functional copy and the docs build does not break. After the lift and shift is complete, we can evaluate the contents and relocate, restructure, and simplify things in parallel with the efforts that the core team will take in the `ansible/ansible` repository.

## To-do before split

The following are items identified during the two-week testing period that need to be resolved before the split occurs:

- [x] Announce and socialize plans via Bullhorn, DaWGs, and Community Working Group.
- [x] Update the issue template in `ansible/ansible` with a checkbox or other pointer to the documentation repo.
-- https://github.com/ansible/ansible/pull/81140
- [x] Work out a review process that ensure technical stewardship from the core team as well as other authoritative reviewers in the community. Also describe how we can reduce additional overhead of a separate repo for docs contributors.
-- https://github.com/ansible/ansible-documentation/issues/36
- [x] Create issues for additional outcomes.
-- https://github.com/ansible/ansible-documentation/issues/34
-- https://github.com/ansible/ansible-documentation/issues/35
- [x] Change GHA to run CI tests when PR is created (aka don't wait for an approval to run the CI tests)
- [x] Change Edit on GitHub in all stable branches in new repo to point to new repo.
-- https://github.com/ansible/ansible-documentation/pull/46
-- https://github.com/ansible/ansible-documentation/pull/45
-- https://github.com/ansible/ansible-documentation/pull/44
- [x] Update how to contribute to docs section to include running `clone-core.py` before building docs locally.
-- https://github.com/ansible/ansible-documentation/pull/37

## To-do after split

- [x] Migrate all related open docs issues from ansible/ansible to the new repo.
- [x] Remove docs and examples directories from `ansible/ansible`
-- https://github.com/ansible/ansible/pull/81011
- [ ] Evaluate how to deal with Antsibull doc warnings
-- https://github.com/ansible/ansible-documentation/pull/21
- [ ] Pin the requirements in `tests/requirements.txt`.
-- https://github.com/ansible/ansible-documentation/issues/30
- [x] Automatically label backport PRs
- [x] Automatically backport all PRs labelled as 'backport_requested'
- [x] update remindbot call for help to point to new doc repo
- [x] ~~update bullhorn call for help to include new doc repo~~ - search string already includes the new repo
- [