Tutorials and how tos for the Ansible ecosystem

Project Discussions
,
1

If you’ve been paying attention to the community docs lately, we’ve been going through a lot of changes with infrastructure. We’ve recently completed a lift and shift of the docsite folder from the ansible/ansible repository to the ansible/ansible-documentation repository.

Moving the docs to a separate repo resolved some issues that were impacting workflows and shared ownership for both the core team and the community. But it has also given us the opportunity to solve a particular challenge, namely that docs across the project ecosystem are missing top-level content that shows how to use all the tooling together for specific use cases.

For example @Andersson007 has recently authored a getting started with execution environments tutorial that combines projects like navigator and builder with community collections: Getting started with Execution Environments — Ansible Documentation

This getting started doesn’t quite fit in the Ansible package docs and it doesn’t fit in ansible-core docs either. We could create yet another repository but that just makes it more difficult for contributors.

So how about we expand the ansible-documentation repository to include the ecosystem? We could create a file system layout similar to this:

docs/
├─ core/
│  ├─ rst/
│  │  ├─ index.rst
├─ ecosystem/
│  ├─ rst/
│  │  ├─ index.rst
├─ package/
│  ├─ rst/
│  │  ├─ index.rst

The ansible-documentation/ecosystem folder holds a new docsite that is intended for cross-project tutorials and how tos.

2 Likes
2

We want to be clear here that the ecosystem is not a replacement for …the Ansible Documentation list of projects. It’s specific ONLY to cross-project how-to guides for example.

The other item to consider - where does it get published? Using the EE getting started guide - it’s published only to the package docs today (Ansible Documentation — Ansible Documentation). So if we move it to the ecosystem folder, does it still publish in the same spot or someplace else?

To be clear - even moving the core files to that new core folder, it would still be part of the Package docs when we publish.

3

I think we should host the ecosystem docs on ansible.readthedocs. Tutorials and how to sit on the top-level. Projects have individual getting started and reference information.

2 Likes
4

I find it confusing that Ansible Documentation looks just like Ansible Documentation

I’m guessing @oranod that the goal is cross-project how-to pages appear above the individual project links on that readthedocs page?

I’m not sure about that level of duplication though.

5

I agree that the temporary duplication is confusing but it’s not something that we really promote to users. I’ve been thinking when the time is right we could set up a redirect from docs.ansible.com/ecosystem.html to ansible.readthedocs.

At some point I can envision ansible.readthedocs being more of a proper docsite with the cross-project how tos and the individual project pages available in a drop-down on the top navigation menu.