port over the ee getting started guide

[oraNod]

This PR moves the "Getting started with execution environments" content from the ansible-documentation repository. As part of this PR, the format is converted from RST to markdown.

The justification for this move is that the content in the ansible-documentation repository focuses on the Ansible package and Ansible core. EEs are outside that scope and involve various projects within the ecosystem.

After this PR is merged and the content is available on readthedoc we'll need to setup redirects from https://docs.ansible.com/ansible/devel/getting_started_ee/index.html. We should investigate whether we can do this from the readthedocs project settings.

[samccann]

LGTM

[Andersson007]

So if i understand correctly, this is gonna move entirely and not be present on docs.ansible.com?
My concerns are:

• EE acceptance and awareness among users is one of top priorities in Ansible.
• This is supposed to become a common way of using ansible-core and collections.
• I understand the rationale but If this guide ends up on one more website where only a few will find it by chance, it would undermine the effort and all the work done (and being done) would be almost in vain, I'm afraid.

Maybe at least keeping the reference on the left side bar would be a good compromise? Not sure

[oraNod]

@Andersson007 Thanks for those details. I see those concerns and agree with what you're saying. Perhaps what this PR is missing is the detail about creating a path for users to discover content. There most certainly should be a connection and link between the package docs and this new ecosystem docsite.

Here is how I would see things going after we merge this PR:

• Add clear links as "next steps" to the Ansible getting started guide. This would take the users directly to the EE getting started after they complete the Ansible getting started to continue learning.
• Add clear links back to the Ansible package docs from the ecosystem documentation.
• Add the Ansible package to the ecosystem page.

What you suggest in that screenshot looks good to me but what if we rename that to "Getting started with the Ansible ecosystem" and link to https://ansible.readthedocs.io/en/latest/index.html

We can create a single page like https://docs.ansible.com/ansible/devel/getting_started_ecosystem/index.html that explains the ecosystem tooling and mentions Execution Environments in a prominent way.

As for the current "Getting started with EE" in the package docs docs.ansible.com/ansible. I say let's leave it on the devel branch until Ansible 9 is released. That will give us time to announce on the bullhorn and seek community feedback. When 9 is released we can set up redirects docs.ansible.com/ansible/.../getting_started_ee -> ansible.readthedocs.io/getting_started_ee

[Andersson007]

@oraNod

What you suggest in that screenshot looks good to me but what if we rename that to "Getting started with the Ansible ecosystem" and link to https://ansible.readthedocs.io/en/latest/index.html

I think the link to the Get started EE guide would work much better than the ecosystem link as the ecosystem is big.
UPDATE: The other ways you mentioned are good and should be implemented but i don't think they fully solve visibility issue considering EE's high priority.

[Andersson007]

So as a summary of the discussion here and on matrix, I think it's OK to move the guides provided that:

• The link on the left side bar on docs.ansible.com (see the screenshot in the comment above) will continue be present in devel, latest, other available doc versions.
• On the ecosystem page, it'll be at the top of the projects list
• It'll also be present on the left side bar of the ecosystem page

Yeah, it's important:)

[oraNod]

@Andersson007 For some reason this isn't clicking with me:

On the ecosystem page, it'll be at the top of the projects list

Do you mean add the EE getting started guide to the top of ecosystem.html?

[Andersson007]

@Andersson007 For some reason this isn't clicking with me:

On the ecosystem page, it'll be at the top of the projects list

Do you mean add the EE getting started guide to the top of ecosystem.html?

@oraNod yes but we can call it Execution Environments

[oraNod]

@Andersson007 For some reason this isn't clicking with me:

On the ecosystem page, it'll be at the top of the projects list

Do you mean add the EE getting started guide to the top of ecosystem.html?

@oraNod yes but we can call it Execution Environments

And we link to the community ee? I'll send a PR now. Let's do that before we merge this.

[samccann]

I agree with @Andersson007 that visibility is important. We get thousands of hits a day on the main docs.

We will run into problems though on 'how many projects need high visibility'. Right now, we want people investigating execution environments. But tomorrow, do we want people investigating DevTools? AWX? etc etc. So I'd suggest maybe a forum topic to discuss how much we put under a 'getting started' section in the Ansible package docs (with the understanding that whatever is there is a stub to point to ecosystem pages).

[Andersson007]

I agree with @Andersson007 that visibility is important. We get thousands of hits a day on the main docs.

We will run into problems though on 'how many projects need high visibility'. Right now, we want people investigating execution environments. But tomorrow, do we want people investigating DevTools? AWX? etc etc. So I'd suggest maybe a forum topic to discuss how much we put under a 'getting started' section in the Ansible package docs (with the understanding that whatever is there is a stub to point to ecosystem pages).

@samccann i understand the concerns but i believe EE is a different thing as: 1) many tools are involved / can use it (i can name at least AWX/Controller/AAP, Builder, Navigator, Runner) 2) it's supposed to be a standard way of using ansible-core + collections our current and new users should be familiar with as soon as possible

[oraNod]

I agree with @Andersson007 that visibility is important. We get thousands of hits a day on the main docs.

We will run into problems though on 'how many projects need high visibility'. Right now, we want people investigating execution environments. But tomorrow, do we want people investigating DevTools? AWX? etc etc. So I'd suggest maybe a forum topic to discuss how much we put under a 'getting started' section in the Ansible package docs (with the understanding that whatever is there is a stub to point to ecosystem pages).

For me this is why I suggested replacing "Getting started with EEs" with something like "Getting started with the Ansible ecosystem" here #4 (comment)

However I take the point from Andrei that it can be tremendously helpful if users adopt EEs at an early stage as they start to expand their automation projects. EEs can act as a bridge to the ecosystem.

[Andersson007]

Provided that all the changes made are about rst -> md formatting, LGTM