Create issues on builder for missing ee docs

[samccann]

Based on community feedback. Some/all of this may end up in the builder guide itself, but as that code is under refactor, just capturing the details here to eventually open up a cleaner issue on the builder repo:

What's missing:

• In general, verify that there are details on how to USE EEs etc.

• The GitOps part mainly, every project using EE is reinventing how to build and publish the container. Another thing is what should be included in a EE, only runtimes or also tools used to tests your playbooks/collection? Lastly, I would know how to version the EE, to me it seems you have to put the EE inside the same GIT repo as the playbooks/collection using it.

• also a unifying place where infos on EE can be found would be nice. right now you have to collect that information together from various projects (ansible-builder, ansible-runner, ansible-navigator) and you never know which other project you missed where some important information is burried
  also the only (to my knowledge) publicly documented EE base images (https://quay.io/repository/ansible/ansible-runner?tab=tags&tag=latest) are horribly outdated

Also note:
there is some refactoring / rewriting work going on with ansible-builder that will change the whole pattern of interaction with EEs. pretty sure this PR is the basis for that effort: ansible/ansible-builder#411

there are also plans to update the community EEs with a new base image and some other stuff.ansible/ansible-builder#411

there was an announcement about runner images ansible/ansible-runner#1199 and there are some community maintained images here ansible/ansible-runner#1138 (comment)

[oraNod]

@samccann FYI this relates to #230

Builder 3.0 is out and it's a good time to tackle the docs. Well, actually it would've been good to tackle docs before the release but that's OK.

My 2c on what is needed from the community is a "How To" guide (following the Diataxis framework) and I've been thinking about where that set of content might live.

If we keep with the Diataxis framework then I think it's reasonable for the Builder docs themselves to contain high-level concepts, tutorials specific to Builder (install and config), plus reference (programmatic options and expected behaviour).

With the "How To" guide in community, what I think would be ideal is perhaps a new section where we can nest this guide and whatever else we identify down the line.

New top-level section: "Ansible How-To Guides"
New guide under that section: "Using execution environments for automation" (or whatever title is the best fit)

What do you think?

[Andersson007]

I'm gonna write a set of guides and i've already started implementing the epic Don mention.
Thanks for sharing the link to Diataxis framework, i'll take it into consideration.
If someone is well familiar with builder, you can write something in parallel and we can incorporate our works later into consistent documentation.
Please investigate the epic first

[oraNod]

@Andersson007 Oh, cool. I didn't fully understand that epic meant you'd be writing docs. If I can help with that, you know where to find me.

[Andersson007]

@Andersson007 Oh, cool. I didn't fully understand that epic meant you'd be writing docs. If I can help with that, you know where to find me.

@oraNod sure, thanks! I'm gonna read those bits of docs we have, play with all that stuff and try to write something (to start with). In the end, it should be a collective-mind product. Once new docs are ready, we'll brush up on them one by one.

[samccann]

@Andersson007 @oraNod I'm inclined to close this issue as most of the work is being tracked by that epic. There's nothing new here except what is in the description and we can copy that into a comment in the epic if we want it all in one place. What do y'all think?

[Andersson007]

@Andersson007 @oraNod I'm inclined to close this issue as most of the work is being tracked by that epic. There's nothing new here except what is in the description and we can copy that into a comment in the epic if we want it all in one place. What do y'all think?

@samccann +1 to closing this topic (sorry, mistakenly clicked Edit instead of Quote reply and accidentally edited your comment)

[oraNod]

+1 to closing from me too. I thought this issue was more about creating opportunities for community contributors but it probably is overlapping with Andrei's epic. Thx.

[samccann]

This work is being coordinated on the epic now #230

Help most welcome on that epic!