# Record of all the docs problems we need to solve

## Non-plugin collection docs

We want collection owners to be able to publish non-plugin docs

* Scenario guides
* tutorials, things not tied to a specific module
* Break out of implementation decisions to be made: https://hackmd.io/pPeMLaFYSt2W8RAqm-ZkXA

### We're not really maintaining the scenario guides
* Moving these to collections allows them to be updated on the proper schedule
* Reduces overhead for people who are making changes to the code itself.

## Version issues

* Ansible and ansible-core will be diverging in version shortly. How is the docsite to deal with Ansible 3.0.0 and ansible-core 2.11 (not to mention ansible-base 2.10 AND Ansible 2.9)?
* Collections also are versioned and those will be different from both ansible and ansible-core versions.
* One version of Ansible may work with / allow multiple versions of ansible-core. How do we show that?
* There will always be a lag between the release of a new ansible-core version and the release of the first ansible version that uses it. How do we show that? Or do we wait to publish them together?
* Given that we want docs.ansible.com/ansible to reflect Ansible the package, how do we handle it when Ansible 3.0.0 releases, and thus becomes latest, but /devel/ is actually ansible-core not Ansible?
* Collections can release multiple versions between one Ansible version and the next. Where/how do we show those docs? Or do we skip intermediate collection versions (as we do today) since they are in AH and presumably Galaxy-ng.

### To version or not to version
We have the opportunity to make some release independent documentation.
* community guide(s)
* developer guide
* tutorials etc

### Pipeline uses Ansible version to set the version in the URL for docs

* If we keep versions in the docs, we have to update the pipeline to get its version number from something other than `ansible--version`

### Out-of-band user updates

* Many users will likely start by installing Ansible and then make updates to a subset of the collections that they really care about. Users should be able to get the documentation for the updated collection somehow (assuming it's been written).

### SEO rankings, canonical versions, and `latest` as a URL

* If we split the docs, creating two URLs (docs.ansible.com/ansible/ and docs.ansible.com/ansible-core) and both sites are versioned and use `latest`, then we could have a `latest` ansible-core that did not work with the `latest` Ansible package, at least briefly following each release of ansible-core
* If we duplicate the ansible-core content (once for Ansible, again for ansible-core), we may get penalized by google and other search engines

## Naming confusion

* ansible-base is being renamed ansible-core

## Translations

* We may have more languages, more versions

## Interdependency

* If we divide docs for "Ansible" from docs for "ansible-core", both sides of the divide would be incomplete - you can't do anything with collections without ansible-core, and you can't do much with ansible-core unless you add at least some collections

## Substandard site search

* This one's self-explanatory

## Clarity of who maintains what
* Splitting the collections from the core allows for ownership of each individual piece. Docs could further that knowledge by separating each piece into its own set of documentation
* Milder implementations of this could merely separate what is maintained by the Core Team or what is maintained by Ansible

## Other problematic docs
* Galaxy guides are in both ansible/ansible and galaxy repo. AFAIK there are no upstream docs at all for galaxy-ng.
*

# Possible and/or partial solutions

### Make users aware of what versions they have installed
* allow `ansible-core --version` as well as `ansible --version`
* add docs describing how to discover both versions and how to navigate to the correct version of the docs for both

### Move scenario guides out of ansible/ansible
* we could create a repo in ansible-collections as a stepping stone between ansible/ansible and the collections `/docs/` folder for scenario guides and other content, or move them directly into collections
* Makes sense from a who-maintains-this POV
* Should be updated as the collections which are the primary source of changes are updated.

### Punt non-plugin collections docs to AH/GalaxyNG
* where is "displaying content from the /docs/ folder" on their roadmap?

### Reorient docs towards documents rather than products
* We have an issue with ansible and ansible-core documentation both being incomplete on their own. Re-orienting the docs away from documenting everything in a package to functional areas ("Plugin Reference", "Inventory Reference", "Writing your first playbook") would allow us to have all docs in one framework.

### Stop versioning the docs, or use dates instead of versions

* would mean editing all the docs to add in "in version 2.9, do x, in version 2.10, do y" or "applies to 3.0 through 5.0"; this would be a lot of work
* tough to use on module docs for any module that's actively changing

### Use Red Hat sites for things that are supported by Red Hat

* KBase, for instance.
* Does this address the "who maintains what" in a better way?