15:00:49 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:49 <zodbot> Meeting started Tue May 17 15:00:49 2022 UTC.
15:00:49 <zodbot> This meeting is logged and archived in a public location.
15:00:49 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:49 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:49 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:00 <samccann> #topic opening chatter
15:01:14 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:22 <briantist> o/
15:01:23 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
15:01:28 <briantist> sorta here, will be distracted as usual
15:01:35 <samccann> #chair briantist
15:01:35 <zodbot> Current chairs: briantist samccann
15:01:44 <samccann> we'll still make ya furniture!
15:01:50 <felixfontein> o/
15:02:04 <samccann> #chair felixfontein
15:02:04 <zodbot> Current chairs: briantist felixfontein samccann
15:02:49 <samccann> https://github.com/ansible/community/issues/643#issuecomment-1122585506 --> agenda
15:02:56 <orandon[m]> o/
15:03:04 <samccann> #chair Don Naro
15:03:04 <zodbot> Current chairs: Don Naro briantist felixfontein samccann
15:03:09 <samccann> Welcome Don Naro !
15:03:54 <samccann> As a bit of intro, Don Naro is joining the upstream docs effort!  He's starting on ...wait for it... getting started guide!!
15:04:14 <orandon[m]> hi everyone! thanks for the intro samccann
15:04:21 <gundalow> That's brilliant
15:04:44 <samccann> yes, very excited. I see great things coming on that guide for sure, which is very timely and needed
15:05:31 <felixfontein> hi orandon[m] :)
15:05:32 <orandon[m]> cheers. I'll give it my best and am delighted to be joining the Ansible docs team.
15:05:38 <orandon[m]> hi felixfontein
15:05:54 <samccann> #topic Documentation updates
15:06:05 <samccann> #info - how much if any execution environment mentions do we want in Ansible docs?
15:06:51 <samccann> Keeping in mind ansible-builder does have its own set of opensource docs. So what do we think we might need in the ansible/ansible docs around this? do we mention it? Are community folks looking into these yet?
15:07:50 <briantist> welcome orandon[m]
15:08:05 <orandon[m]> thank you briantist glad to be here
15:09:13 <samccann> I feel like for EEs (execution environments) maybe we should mention them as an option somewhere in the collection developer docs, but maybe just a heading and intro paragraph, then pointer to the builder docs?
15:11:21 <felixfontein> I think that belongs both in the dev guide and user guide
15:11:42 <felixfontein> building EEs is more for users than devs, but devs need to know how to prepare their collections for EEs
15:12:15 <samccann> are there any community EEs availablre for users yet?
15:12:50 <felixfontein> you mean pre-built ones? not really, though I hope that can change today once the next Ansible 5.x.0 release is out
15:13:10 <samccann> ok so it's timely then to find a way to add to user content and dev content
15:13:30 <samccann> #action samcann open issues for adding basic EE info to user and collection dev guides
15:13:37 <samccann> that brings up another question
15:13:46 <samccann> Anyone have details on meta/execution-environment.yml ?
15:13:54 <felixfontein> "details" :)
15:13:59 <samccann> like what the format is etc?
15:14:13 <samccann> cuz I'll need that for the dev guide changes for sure
15:14:27 <felixfontein> I looked at the ansible-builder code to figure out what exactly it can do (tldr: not that much), I'm not sure whether it's documented anywhere yet
15:14:50 <samccann> yeah afaik it isn't documented in builder yet
15:15:08 <samccann> so maybe I'll ask those folks. then I can pop a PR over there and point to it from our docs or something
15:15:30 <samccann> #action samccann to ask builder team about meta/execution-environment.yml
15:15:47 <felixfontein> it makes sense that ansible-builder documents that file, since they are its only consumer (AFAIK) :)
15:15:53 <samccann> oh should explain ^^ that file is in the collection structure but we don't mention it at all in docs
15:16:37 <samccann> #topic doctools
15:16:58 <samccann> speaking of community-based EEs :-)
15:17:24 <samccann> Do we need/want some way to pull them into the docsite like we do collections?
15:18:06 <samccann> do we see them as a growing list of community EEs people are interested in? Do we find some other place to document them (since afaik they will never be part of the Ansible package so maybe not part of the docs themselves)?
15:18:34 <felixfontein> that's a very good question. right now there is no place I know of that actually collects community EEs
15:18:47 <felixfontein> except https://github.com/ansible-community/images/ :)
15:19:34 <samccann> so that brings up more questions :-)
15:19:46 <samccann> Do we want that to be the 'central repository' for community EEs?
15:20:05 <samccann> Or is that restrictive, and some people will want their EEs somplace else?
15:20:07 <felixfontein> no idea... TBH
15:20:29 <samccann> ok maybe that's a question for the community team meeting tomorrow
15:20:34 <samccann> or a community-topic?
15:20:34 <felixfontein> that's probably a topic for community-topics ;-) and maybe something that can only be properly answered if there are actually a handful of them
15:21:08 <thedoubl3j> o/
15:21:09 <samccann> well the initial question could be answered - do we want that repo you pointed to as the recommended place users can find EEs for community use
15:21:17 <samccann> #chair thedoubl3j
15:21:17 <zodbot> Current chairs: Don Naro briantist felixfontein samccann thedoubl3j
15:21:20 <samccann> welcome!
15:21:27 <thedoubl3j> apologies for the tardiness
15:21:46 <samccann> no prob and very timely since you probably know more about users and EEs than I do for sure
15:22:41 <thedoubl3j> Knowledge kinda only sits in the kitchen side of things (creation and bits needed for EEs)
15:23:05 <thedoubl3j> let me read and catch up right quick
15:24:47 <thedoubl3j> I can comment at least on the meta/execution-environment.yml
15:24:58 <thedoubl3j> the example found here,,,
15:25:26 <thedoubl3j> https://ansible-builder.readthedocs.io/en/stable/definition/ is the basic one
15:26:02 <thedoubl3j> when we sent out the emails to partners asking them to update, we also sent that along as a template (some slight changes).
15:26:41 <felixfontein> thedoubl3j: but that does not document meta/execution-environment.yml
15:26:52 <samccann> yeah that is mentioned here -https://ansible-builder.readthedocs.io/en/stable/collection_metadata/
15:27:06 <felixfontein> that example is for the file that defines an EE, but not for meta/execution-environment.yml inside a collection
15:27:15 <thedoubl3j> no, it doesn't. which we handily found out because partners asked about it
15:27:28 <samccann> haha so watch that space and it'll get updated soon, eh?
15:28:02 <felixfontein> thedoubl3j: I also noticed when I thought that additional_build_steps would solve some of my problems - unfortunately it isn't available :)
15:28:15 <samccann> so from your perspective thedoubl3j - is there already a 'hosting' place for EEs that aren't officially supported? I seem to recall a quay something or other but I don't know if that's something we should dig into as a possible expansion place for community EE hosting etc
15:28:25 <felixfontein> (I need to install a system dependency that's not available in RHEL and EPEL)
15:30:27 <thedoubl3j> for hosting I am not sure. I am not aware of any one place currently, quay could be a place.
15:30:55 <thedoubl3j> when we first started pointing folks to it, we hosted our upstream images there, think some are still there. (note these are the base images)
15:30:58 <samccann> ok perhaps I have a fundamental misunderstanding on EEs. DO they need a common place to fetch them?
15:31:13 <thedoubl3j> so not actually EEs, just the images that EEs are based off of.
15:31:30 <samccann> so as a user of community.general, if they create an EE for it, how would I find out for example?
15:32:01 <thedoubl3j> if they create it, for you to find out about it, they would need to publish it.
15:32:31 <samccann> ok I should dig into this more before I ask all the qauestions in the world lol
15:33:56 <samccann> #topic splitting doctools into a separate channel
15:34:14 <samccann> So this is a new idea. We have a group of volunteer writers that may be joining here.
15:34:40 <samccann> They are in discord today so that might be a bridge. I was thinking a bridge to a new channel ( say doc-writers)
15:35:08 <samccann> but it was brought up that maybe it shoudl bridge to this docs channel, and we consider a separate doctools channel for the techie stuff (antsibull etc)
15:37:09 <samccann> The reason I'm considering separate channels (no matter which one we do) - these writers come with different levels of experience and I want a place where they feel safe to ask any and all questions, and also follow along and understand.
15:37:43 <samccann> I think doctools is the biggie that would just flood them with an overwhelming level of detail on stuff they would never deal with really
15:37:56 <thedoubl3j> I like that idea (2 channels)
15:39:08 <samccann> felixfontein: briantist what do you think since it would be a lot fo your work that would switch if we did a docstools channel
15:40:44 <bcoca> https://github.com/ansible/ansible/pull/77423/ new tests, but has new docs also
15:41:31 <felixfontein> sorry, was busying restoring admin access with a postgres shell ;)
15:42:07 <felixfontein> I don't mind having one or two channels. one thing to consider is that right now, bot the docs and the doctools part in this channel are both low-traffic
15:42:37 <felixfontein> and I'm not sure how much more traffic doctools would get anytime soon
15:42:50 <felixfontein> (probably less when nothing interesting is happening, like a new feature coming soon ;) )
15:43:12 <samccann> that is true
15:43:43 <samccann> maybe I should just go back to the discord group and ask them what they think.
15:44:33 <samccann> ah should have infoed this a bit
15:44:50 <samccann> #info we could split doctools to a separate channel to keep this one docs focused (words on paper)
15:45:21 <samccann> #info this would help new community writers, but this channel doesn't get a lot of doctools chatter except in meetings so may not be necessary
15:45:43 <briantist> sorry, I will need to come back and review most of this I'm really overloaded right now
15:46:23 <samccann> #topic  sample output for return values
15:46:32 <samccann> #info can we create a 'sample' output for return values in module docs? Got feedback that a fully-formed example would help people understand it better.
15:47:11 * felixfontein just changed to another room, so now you have my full attention :)
15:47:14 <samccann> I looked at the code and it seems the values are there(and are surfaced in the individual return value tables as samples)
15:47:35 <samccann> but someone suggested it would be easier to understand if it was shown as an example as well
15:48:05 <felixfontein> do you mean having a concrete `RETURN` variable content listed somewhere in the docs as an example?
15:48:45 <samccann> so if you look at the return table, there are sample output on each line
15:49:06 <felixfontein> ah
15:49:09 <samccann> so what I suggest is after the table, we add a 'return example' and just put all that info in one well-formed output
15:49:39 <felixfontein> so a *complete* return example instead of the example spread out over the table
15:50:14 <felixfontein> that definitely requires core support, I guess it would be a new section (next to DOCUMENTATION, EXAMPLES, RETURN)
15:50:52 <bcoca> i would not make it separate, but a key in RETURN
15:50:58 <bcoca> full_sample or similar
15:51:27 <bcoca> but that can get really out of hand ... facts/info modules ...
15:51:32 <felixfontein> probably more _full_example to peevent confusion with regular return values?
15:51:36 <felixfontein> s/peevent/prevent/
15:51:58 <samccann> well I guess my initial question  - can this be 'solved' with code? As in can what exists today in py files for return be used to create this example?
15:52:38 <felixfontein> samccann: I don't think so. simply combining all the samples from the individual keys will in general produce garbage
15:53:13 <samccann> ah ok
15:53:33 <samccann> I was thinking it would result in something useful. Sounds like maybe it wouldn't
15:53:39 <felixfontein> (for some modules/plugins it will work fine, for others not so, and for some it probably will be horrible and pretty much wrong :) )
15:53:52 <samccann> in which case, adding something like this would require 3000+ modules to update with said example. Kinda painful
15:54:22 <felixfontein> well, also there are quite a few modules which don't even document their existing return values
15:54:47 <bcoca> we 'can' append all the samples to 'full sample' but that would require the author to keep them congruent
15:55:10 <samccann> #info the existing return value samples are per-key and not authored necessarily to be a consistent full example. The result of using this info could produce garbage
15:55:20 <bcoca> maybe only generate if _full_sample_safe= false|true flag is set?
15:56:06 <felixfontein> bcoca: that would make sense
15:56:18 <samccann> So technically, we could add something, but it would be a new addition to each plugin py file and only show up if present, so to speak.
15:56:24 <felixfontein> bcoca: but even then there are some potential complications when `contains:` is used
15:56:31 <samccann> Next question - is it worth it? I'm going on feedback from one user
15:56:34 <bcoca> recursive!
15:57:02 <felixfontein> bcoca: sometimes options with `contains:` have a sample, sometimes not. and if they have, sometimes it is a useful example for the whole option, sometimes it is not
15:57:03 <bcoca> well, you either have sample at top, or at each' contained'
15:57:26 <bcoca> so if take 'top' if exists, otherwise look at contained
15:57:33 <felixfontein> I guess the person setting _full_sample_safe=true would have to check whether the result makes sense before setting it
15:58:26 <bcoca> if it makes no sense, bug for author
15:58:30 <felixfontein> the hardest part is probably defining a schema for validating RETURN that is hopefully also a JSON schema
15:58:42 <samccann> hmm
15:59:02 <samccann> we can't put something in place that would automagically create a sample that makes no sense.
15:59:16 <samccann> I mean if the author WROTE the full example and it's wrong, that's one thing.  and yeah, bug for author
15:59:37 <felixfontein> indeed
15:59:57 <samccann> ooch time flies
16:00:02 <samccann> we have one minute left for open floor
16:00:13 <samccann> #topic Open Floor
16:00:18 <samccann> anyone have anything to bring up? now's the time!
16:00:39 <felixfontein> actually, I ... *timeout* ;)
16:00:40 <samccann> favorite doc/pr/issue that isn't getting attention? Some other docs idea?
16:00:58 <samccann> LOL
16:01:18 <felixfontein> bcoca: out of curiosity, what's the state of sidecar docs/ sivel mentioned that some refactoring would happen
16:01:24 <felixfontein> replace / with ? ...
16:01:47 <bcoca> https://github.com/ansible/ansible/pull/77719 <= refactoring, trying to make easier for others to use api to get sidecar info, also fixing some bugs
16:02:36 <felixfontein> thanks!
16:03:58 <samccann> ok if we don't have anything else..??
16:04:24 <samccann> #endmeeting