owned this note
owned this note
Published
Linked with GitHub
# 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?