Determine location for the EE overview page and the Build and test first EE quickstart guide.

[Andersson007]

A subtask for epic #230

The EE overview and the Building and testing first EE quickstart guide have been merged.

Let's determine its location.

Some time ago I was thinking about putting it in the builder's docs.
However, after discussing it with @Spredzy we think docs.ansible.com is a right place because:

• Users should get the general concept and basic info on how to quickstart with building and testing stuff on docs.ansible.com
• The tool specific docs like for builder will contain exhaustive info for those who want to go deep
• The EE overview and the Quickstart guide will contain refs to those tool-specific docs

Let's discuss this.

1. Does everyone agree that the docs mentioned above should live on docs.ansible.com?
2. Where exactly? Please suggest your paths

After there's a consensus, I'll submit a PR

[Andersson007]

cc @Spredzy @oraNod @samccann this is a blocker for further work, so please put your feedback as soon as possible

[oraNod]

My 2c on all of this.

I see the Ansible community docs like this:

• Package docs (everything you get with pip install ansible) - lives at "docs.ansible.com/ansible"
• Ansible project docs (concepts, reference, tutorials) - lives at "ansible.readthedocs.io"
• Ansible how tos (end to end scenario guides) - lives at "docs.ansible.com/howto"

Package docs and How Tos should reside in the new ansible/ansible-documentation repository. That gets built to what is currently docs.ansible.com. Project docs are in the ansible github org and are built in the ansible namespace on read the docs.

I think the content from the PR is a good start but I don't think it is yet a full "How To" for docs.ansible.com.

The overview is slightly repetitious with https://ansible-builder.readthedocs.io/en/latest/#introduction-to-ansible-builder

I also feel like the building and testing that postgres ee is really more of a tutorial. I could see that as a new chapter / left-nav section in the builder docs.

The difference between tutorial and how to is this:

• A tutorial teaches someone knowledge or skills that they do not currently possess.
• A How to teaches someone to apply existing knowledge or skills.

I badly want us to start with the How Tos on "docs.ansible.com" but I don't think we're there just yet and it seems like we're rushing it a little. I don't want us to end up having to make too many changes on docs.ansible either.

[Andersson007]

I think the overview and the tutorial are general (they don't relate to builder only).
imo there should be dedicated pages somewhere under the ansible user guide

[oraNod]

Wouldn't putting them under the user guide add the content to the package docs?

I don't want to be difficult about it but I think if we put the overview and tutorial under the user guide, we'll need to move them again down the line.

[samccann]

How-to guides that cross projects like EE, should have their own 'home' somewhere. They are inherently not tied to one specific version. Using the how to build/test first EE tutorial as an example - it uses builder v3 and ...what version of navigator? So what branch of ansible/ansible-documentation would this how-to guide live in? Neither of the projects in this how-to actually specify either an Ansible package release or an ansible-core release.

I suggest our how-to cross-project guides should be unversioned and live in their own repository. So we'll have this and maybe a few other scenarios for EEs.
Within the how-to guide, we specify the guide was tested on version 3 of builder, xx of navigator, incorporated 2.15 of core, etc.

Then in the future, maybe we have howto guides that show how to use VScode to write playbooks with ansible-lint and ansible lightspeed. Three projects in one guide.

When next we update (which btw, we haven't determined how or when or who will update these guides after they are initially written) - we replace the existing how-to with the updated one, complete with updated versions of projects included.

As for this specific how-to - it's not quite a tutorial as it combines two projects. A simple tutorial for builderv3 wouldn't use navigator as you are introducing two projects to someone who just wants to know what an EE is and a step by step hand-holding on how to create a simple one. So next steps on that merged PR could be:

1- integrate the overview with the builder docs. note they were updated recently so it should integrate, not overwrite what was just done.
2 - decide if the other page wants to be a tutorial - if so, trim out navigator and use ansible-builder introspect instead to validate the EE. Simplify the steps.. The goal is a hand-holding step by step that lands the reader with an EE they can use 'somewhere'. I don't think an EE can be used by itself (outside of navigator/awx/runner) so may not be able to show it with a playbook. Then add it as part of the existing builder quickstart section.
3. Alternately, rewrite the tutorial to be a how-to guide. A how-to guide assumes the person understands the basics. It also should be opinionated (aka just use podman, not docker etc) and focus on how to build and validate an EE before putting it into 'production' somewhere. Less hand-holding, more step 1, step 2, etc.

Overall comment - we are still shooting from the hip on our overall Ansible community content strategy and information architecture. Unless we pause and spend a dedicated month to review everything and consider what goes where, what is unversioned, what has versions, what is package vs core vs community vs how-to-cross-project etc etc - we will inevitably have to move things around again and again.

[Andersson007]

1- integrate the overview with the builder docs. note they were updated recently so it should integrate, not overwrite what was just done.

EE is a concept broader than builder, so not sure why the EE overview should be merged with the builder introduction page.
EE is a way to use Ansible (core + collections), really not sure why this doesn't fit Ansible user guide. EE was created to mitigate users' pain caused by collection dependencies.
To be clear, the goal is to make our users accustomed with EE as with a standard way to use Ansible. The main goal is not to improve each tool doc slightly.

2 - decide if the other page wants to be a tutorial - if so, trim out navigator and use ansible-builder introspect instead to validate the EE. Simplify the steps..

The introspect command is not for validating the images.
The goal of the Quick-start guide (it doesn't pretend to be a how-to) is to mitigate the entry threshold for potential users w/o making them jumping here and there across sites of several tool (as i painfully did).
The plan is:

1. Give potential EE users EE overview
2. Then give them the Quick-start guide (aka that merged tutorial)
3. If they wanna go deeper, there'll be links to tool-specific docs.

How-tos is another story. Are quick-start guides/tutorial mutually exclusive with how-tos?

It's hard to work with the docs we have now, really.. I spent a couple of days trying to create a consistent picture in my head and ended up testing it with errors and ansible-runner which is a hard way and didn't know that it's more convenient to test it with navigator, etc. etc.
We shouldn't assume our user is an expert in containers, ansible-buider, ansible-runner, AWX, knows the nuances, etc.
In order to popularize the technology, IMO, we need something potential users go through w/o pain in one place and doesn't require intuition of a very experienced IT person, stuff that just works so that they have an impression from the beginning "it's easy to understand and run".

[oraNod]

I've been thinking more about where this fits.

Maybe some of the difficulty with positioning the docs comes from the fact that builder is the kind of thing that runs under the hood. I was thinking the builder docs mostly because this just isn't a How To in the broader sense. I think there's still work done to define those things as part of the writer's toolkit.

@Andersson007 I think you nailed it when you said it's more of a quickstart. What if we expand the Getting Started section in ansible_index.rst to add the overview and tutorial there?

That could tie in nicely with the effort to make the getting started more focused on projects as part of ansible/ansible#80941

"You've installed the package and now want to quickly increase your working knowledge of Ansible? Great, here is another tutorial that builds on the concepts that you just learned."

Getting started feels like the right place for this content to me. It works and would be good to have one or two more tutorials under that section. WDYT?

[samccann]

fundamentally we need to decide - are package docs ...docs for the package or not?

Adding other projects to the package docs means they aren't package docs anymore, they are ansible ecosystem docs. Perhaps that is the direction we should go in, but it should be brought up for higher community discussion imo.

[oraNod]

@samccann I know what you are saying but I feel like people who do "pip install ansible" are installing Ansible and don't think about the package in the way we do.

I agree that we shouldn't shove too much stuff into the package docs. At the same time we shouldn't create more fragmentation.

While I think the How To content is something new and we need to figure it out, I think it makes sense to have a single getting started section. Andrei's ee overview and tutorial builds on concepts in the existing getting started. Plus containerization is kind of a standard thing these days so it makes sense to explain how Ansible approaches all that.

A getting started with the ecosystem would be a really small set of content that would exist in a silo. I really think that would just end up with more fragmentation.

How about we send a PR? I really do think that if we can get this ee overview lined up with the revamp of the existing getting started it will make a lot more sense.

If we can't work it out in the PRs then let's take it to the wider community discussion.

[samccann]

@Andersson007 - we talked about it in today's DaWGs meeting and the recommendation is to move these EE introl/getting started into a PR in the ansible/ansible-documentation repository here -
https://github.com/ansible/ansible-documentation/tree/devel/docs/docsite/rst/getting_started

It will be its own guide "Getting started with Execution Environments" or something like that. It won't be part of the existing getting started but will be below it in the left-hand navigation. something like:

| Ansible Getting Started
|-- Getting started with Ansible
|-- Getting started with execution environments (or whatever title works best)

Title might have to be shorter :-)

[Andersson007]

@Andersson007 - we talked about it in today's DaWGs meeting and the recommendation is to move these EE introl/getting started into a PR in the ansible/ansible-documentation repository here - https://github.com/ansible/ansible-documentation/tree/devel/docs/docsite/rst/getting_started

It will be its own guide "Getting started with Execution Environments" or something like that. It won't be part of the existing getting started but will be below it in the left-hand navigation. something like:

| Ansible Getting Started |-- Getting started with Ansible |-- Getting started with execution environments (or whatever title works best)

Title might have to be shorter :-)

@samccann SGTM, thanks:) I'll submit the PR ASAP

[Andersson007]

@oraNod @samccann created a PR to move the docs ansible/ansible-documentation#18
please take a look

[Andersson007]

Closing this as done. Thanks everyone!