# Tutorials and how tos for the Ansible ecosystem

**URL:** <https://forum.ansible.com/t/tutorials-and-how-tos-for-the-ansible-ecosystem/122>\
**Category:** Project Discussions\
**Tags:** feedback-wanted, documentation\
**Created:** [August 15, 2023, 4:21pm UTC](https://forum.ansible.com/t/tutorials-and-how-tos-for-the-ansible-ecosystem/122 "2023-08-15T16:21:50Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [August 15, 2023, 4:21pm UTC](https://forum.ansible.com/t/tutorials-and-how-tos-for-the-ansible-ecosystem/122/1 "2023-08-15T16:21:50Z")

</div>

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](https://docs.ansible.com/ansible/devel/getting_started_ee/index.html)

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:

```auto
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.

---

<div class="post-metadata">

**Author:** ![samccann](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/samccann/32/18_2.png) [@samccann](https://forum.ansible.com/u/samccann)\
**Post date:** [August 21, 2023, 8:55pm UTC](https://forum.ansible.com/t/tutorials-and-how-tos-for-the-ansible-ecosystem/122/2 "2023-08-21T20:55:26Z")

</div>

We want to be clear here that the ecosystem is not a replacement for …the [Ansible Documentation](http://docs.ansible.com/ecosystem) 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](http://docs.ansible.com/ansible)). 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.

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [August 23, 2023, 9:41am UTC](https://forum.ansible.com/t/tutorials-and-how-tos-for-the-ansible-ecosystem/122/3 "2023-08-23T09:41:56Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![samccann](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/samccann/32/18_2.png) [@samccann](https://forum.ansible.com/u/samccann)\
**Post date:** [August 23, 2023, 8:31pm UTC](https://forum.ansible.com/t/tutorials-and-how-tos-for-the-ansible-ecosystem/122/4 "2023-08-23T20:31:59Z")

</div>

I find it confusing that [Ansible Documentation](https://ansible.readthedocs.io/en/latest/) looks just like [Ansible Documentation](https://docs.ansible.com/ecosystem.html)

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.

---

<div class="post-metadata">

**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\
**Post date:** [August 28, 2023, 5:01pm UTC](https://forum.ansible.com/t/tutorials-and-how-tos-for-the-ansible-ecosystem/122/5 "2023-08-28T17:01:44Z")

</div>

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.