15:01:25 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:25 <zodbot> Meeting started Tue Oct  4 15:01:25 2022 UTC.
15:01:25 <zodbot> This meeting is logged and archived in a public location.
15:01:25 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:25 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:25 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:32 <acozine> o/
15:01:37 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:41 <samccann> #chair acozine
15:01:41 <zodbot> Current chairs: acozine samccann
15:01:46 <DonNaro[m]> o/
15:01:52 <DonNaro[m]> finally not double booked!
15:01:57 <DonNaro[m]> hello acozine
15:01:57 <acozine> I'm working on a thing I need to finish today, so I'm happy to be a chair but I won't be fully here today
15:02:24 <samccann> ok thanks acozine
15:02:27 <samccann> #chair Don Naro
15:02:27 <zodbot> Current chairs: Don Naro acozine samccann
15:02:30 <samccann> and congrats!!
15:02:54 <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:03:45 <samccann> felixfontein: briantist you around to talk docs today?
15:04:18 <samccann> Official agenda is https://github.com/ansible/community/issues/643#issuecomment-1259760321
15:05:10 <samccann> #topic Action Item updates:
15:05:29 <samccann> #info resolved weekly staging of Ansible 7 and core 2.14 docs available on test
15:05:31 <samccann> urls in a bit on that one
15:05:34 <samccann> #info open - Consider an 'open docs hr' later in the week to regularly interact with docs contributors in a friendlier way than the expert details that happen in DaWGs meetings
15:05:46 <samccann> #info open add a link to a separate intro to the agenda for welcome/here's what you need to know/ etc so newcomers can prepare.
15:05:57 <samccann> #topic docs open hrs on matrix
15:06:28 <samccann> So we talked about this a bit back - this meeting gets VERY technical very fast and may not be the best place for newcomers to documentation to get involved.
15:06:51 <samccann> So the idea of having a docs open hour at a different time during the week seemed like a reasonable solution. So now.. which day? which time??
15:07:19 <samccann> looking at the existing WG meetings, there's nothing on Mondays, and less on Thursday afternoons so those are two possibilities.
15:08:01 <DonNaro[m]> I'd prefer Thursdays to keep it casual, closer to the weekend and more fun
15:08:37 <samccann> yeah that's true. Mondays might be rushing it.. I'm a slow starter on the workweek :-)
15:09:02 <samccann> But we're separated by 5 hrs... so when is it too late for you?
15:09:33 <samccann> oh looking at existing meetings, we could do Thursday morning (my time) which would still be reasonable o'clock your time
15:10:48 <samccann> #info proposal is to add another informal docs open hour to the WG meeting list for people wanting to discuss or drop in wit hquestions/help on actual words-on-paper docs things
15:10:51 <DonNaro[m]> I would prefer earlier. maybe we could split things and have an EMEA time and a NA time
15:11:04 <DonNaro[m]> * NA time?
15:11:15 <cybette_> alternate weeks perhaps?
15:11:17 <samccann> what do you think about 10 AM ET (one hr before this time)?
15:11:34 <cybette_> sorry to interrupt, just walked by :)
15:11:47 <samccann> or yeah, we could alternate.. not sure how to get that working in the meeting calendar but I'm sure there's a way
15:11:48 <DonNaro[m]> hi cybette
15:11:49 <felixfontein> sorry, I'm a bit busy right now...
15:11:50 <samccann> haha #chair cybette
15:11:57 <samccann> that's what we do to walk bys!
15:12:10 <felixfontein> but please check out https://github.com/ansible-community/community-topics/issues/143 everyone ;)
15:12:14 <felixfontein> it's docs related ;)
15:12:19 <cybette_> hi! haha it's ok I don't need to be chair, not going to stay long enough to sit
15:13:41 <cybette_> for the calendar you can specify every two weeks, but you'll probably need 2 calendar entries (one for EMEA, one for NA)
15:13:50 <samccann> lol thanks felixfontein I have that on the agenda for later as well
15:14:33 <samccann> ok so should we  try that Don Naro ? or try just the one time on Thursday and see how it goes?
15:14:45 <samccann> I'm guessing it won't have a lot of participation at the start, but who knows
15:14:47 <DonNaro[m]> maybe let's try the one time on Thursday and see how it goes
15:14:54 <samccann> ok cool
15:14:59 <DonNaro[m]> kick things off and refine later
15:15:36 <samccann> #agreed will start Open Docs hours on Thursdays, 10AM ET
15:15:59 <samccann> #action samccann dnaro - create calendar entry to get the open docs hours on the WG calendar
15:16:38 <samccann> #topic announcement
15:16:55 <samccann> #info welcoming dnaro to the Ansible community engineering team!!!
15:17:14 <cybette_> 🎉
15:17:19 <Dhee5096[m]> Hi
15:17:27 <samccann> yes, he's been lurking, he's been participating, he's been dual-meeting it for a few months, but now we have him in our evil clutches 100%!
15:17:28 <samccann> and we ain't lettin go
15:17:28 <DonNaro[m]> haha
15:17:47 <DonNaro[m]> thanks! it's great to officially be part of the team.
15:17:58 <samccann> Welcome Dhee#5096 !
15:18:06 <DonNaro[m]> welcome Dhee#5096
15:18:07 <samccann> #chair Dhee#5096
15:18:07 <zodbot> Current chairs: Dhee#5096 Don Naro acozine samccann
15:18:17 <cybette_> Hi Dhee#5096 !
15:19:04 <Dhee5096[m]> Thank you. What’s the discussion on the docs today about?
15:19:57 <samccann> So what we just finished talking about - we will have a docs open office hours at 10AM ET on Thursdays soon. This will be a place to talk more about docs etc
15:20:27 <samccann> this meeting tends to get deep into the weeds on how we create the docsite etc and is hard for people to really get involveed in (unless they are working in those weeds :-)
15:21:46 <Dhee5096[m]> Cool, would it hold this Thursday?
15:21:54 <Dhee5096[m]> Or the next?
15:22:15 <samccann> Don Naro: and I need to discuss. I have a meeting overlap this week and then I'm on vacation next week.
15:22:40 <Dhee5096[m]> Alright then
15:23:20 <samccann> #topic Documentation updates
15:23:54 <samccann> So we are participating in Hactoberfest this year (a month-long open source event where we put up easy to fix issues for people to help out with
15:24:03 <samccann> #info 24 issues closed so far for hacktoberfest. Busy times!
15:24:59 <DonNaro[m]> yeah there has been a flurry of hacktoberfest PRs for docs
15:25:13 <DonNaro[m]> you love to see it
15:25:30 <samccann> first few days are definitely frantic. And we are out of issues already! We have some ideas to create more as well
15:26:40 <samccann> #info Ansible 7 alpha staged at http://docs.testing.ansible.com/ansible/latest/index.html
15:26:46 <samccann> #info ansible-core beta staged at - http://docs.testing.ansible.com/ansible-core/2.14/
15:26:58 <samccann> We'll stage weekly going forward so feedback most welcome
15:27:19 <samccann> which brings me up to...
15:27:24 <samccann> #topic sidecar docs
15:28:05 <samccann> So bcoca added a feature to core 2.14 to support documenting filter and test plugins as 'side car' yaml files. Since these plugins tend to be a batch of them in one file.
15:28:17 <samccann> that's the good news
15:28:41 <samccann> the bad news? now that we are staging the docs, there are a bunch of error pages from collection owners w ho have these plugins but don't have docs to go with them
15:28:58 <samccann> So my first question - did we ever tell collection owners this was coming?
15:29:27 <samccann> my second question - do we have docs to explain what they need to do? I did a quick check but don't see any in the dev guide. bcoca do you have any docs around this?
15:29:48 <samccann> (@bcoca ... saying it 3 times to see if he shows up like Beeteljuice!)
15:30:10 <samccann> felixfontein: adding you as well in case you happen to know if this was communicated?
15:30:43 <samccann> I'll need to open a batch of issues so I'd like to know if I have to open as 'mea culpa we forgot to tell you about this but can you please get these docs in place asap before Ansible 7 releases)'
15:31:26 <bcoca> i wrote some, but not published, for developing plugins as an option for docs
15:31:54 <bcoca> ansible-doc just posts those as UNDOCUMENTED had expected docs build to do same
15:32:17 <samccann> BEETELJIUCE! IT WORKED
15:32:18 <samccann> :-)
15:32:18 <samccann> bcoca: not sure I understand 'for develping plugins as an option for docs'
15:32:33 <samccann> is that what you did with the filter yaml files you created for the builtin stuff? or something else?
15:33:37 <bcoca> sectio developing plugins -> docs (right now they are inline in .py, this gives .yml option)
15:34:14 <samccann> is there a draft Pr of that somewhere?
15:35:04 <samccann> I'm also not sure what we want to do for the errors - do we want an 'undocmented' message for these on the docsite, or leave them as errors to help encourage collection owners to document them?
15:36:26 <bcoca> i would say both methods 'encourage' documenting
15:37:13 <samccann> To those following along - we never had the ability to document  these filter and test plugins until core 2.14 (which hasn't released yet). So we have a couple of problems identified here;
15:37:13 <samccann> 1 - communications - I'm guessing we haven't let collection owners know about this feature so we need to figure out how to 'be better' in the future so to speak.
15:37:54 <samccann> 2 - what do we do NOW - either undocumented or error message both mean users are aware these filters/test exist now (which is good) but have no info about them (which is... not so good).
15:38:32 <bcoca> we made it part of roadmap and have been disucssing in community, not sure what else needed to be done
15:38:54 <bcoca> well, before they had no info at all .. so improvement!
15:39:28 <bcoca> also the community team changes might have created a vacuum at worst time possible
15:40:02 <samccann> So the roadmap gives no indication that there is an 'action item' coming from it for collection owners fwiw
15:40:51 <samccann> but in general, I think we need to identify 'you need to do something when this hits' features and yes, the community team can help with this for sure
15:41:32 <bcoca> well, we added the faciltiy to add docs, but it is not a mandate from the core side
15:41:34 <samccann> looks like about a dozen collections impacted
15:41:51 <bcoca> i would expect 'every' collection that has filters/tests
15:42:07 <samccann> yeah. just looking at the docsite, that's about 11
15:42:12 <samccann> on a quick scann
15:42:20 <bcoca> orhter plugins are more 'mandate' cause the docs == config == requried for execution
15:42:25 <samccann> are sidecar docs coming for any other plugin type or just these two btw?
15:43:05 <bcoca> need to x2 check, but the intention is to be available for all (though practically only shouild be used in filters/tests/non python modules
15:43:09 <bcoca> )
15:43:56 <samccann> #info sidecar docs are intended for filter/test/non-python modules
15:44:27 <samccann> just so I don't lose that tidbit.  Are we able to put a stake in the ground and say nope, you can't use this for other plugin types?
15:44:50 <samccann> as in there's no reason we know of for someone to STOP using docstrings in python files etc?
15:45:23 <bcoca> creazy optimization on modules ? no docstrings means less data to copy over and execute
15:45:44 <samccann> ah ok
15:46:02 <samccann> well I think we leave THAT optimization option... undocumented :-)
15:46:04 <bcoca> for plugin types that it is docs only, 'less loaded inm emory' but that is tiny optimization, config type plugins require reqding it anyways
15:46:36 <samccann> #action samccann to open issues on impacted collections for filter/test plugin docs
15:47:54 <samccann> #topic doctools
15:48:10 <samccann> #info parameter values enhancement to discuss - https://github.com/ansible-community/community-topics/issues/143
15:48:39 <samccann> felixfontein: has an enhancement to the plugin docs that makes it more obvious what values are (string vs something else etc)
15:48:56 <samccann> so please go take a look. I expect we'll finalize by end of week on this
15:50:41 <samccann> #topic Open Floor
15:50:54 <samccann> Here's the time to bring up anything else on your mind related to docs
15:53:54 <DonNaro[m]> samccann: Last thing with the user guide rewrite is setting up the redirects. Could you remind me about the ideal date for them to be in place?
15:54:15 <samccann> oh good point! That's tied to the core release
15:54:17 <DonNaro[m]> I'm still grabbling with release dates and when things need to happen
15:54:19 * samccann checks date
15:54:52 <samccann> 11/7. So let's target 1st of Nov
15:55:46 <DonNaro[m]> great. I don't suppose we've had much feedback on all those changes, have we?
15:55:58 <samccann> No, but we don't get a lot of traffic on devel docs compared to latest
15:56:04 <DonNaro[m]> I've been lurking around reddit and trying to keep an eye out but maybe because they're on devel the changes won't have got much attention
15:56:07 <DonNaro[m]> snap
15:56:12 <samccann> you posted on reddit?
15:56:32 <DonNaro[m]> no, no. just been looking for any mention. the getting started guide came up there once.
15:56:59 <DonNaro[m]> it seems to be the main place, apart from here, where folks talk about the core docs
15:57:30 <samccann> i think it's been in the bullhorn a couple of times? That's the other place were we could pre-announce with a link to devel docs?
15:59:15 <DonNaro[m]> yeah it's had a couple shouts in the bullhorn. I guess it's fine then. just part of me wonders how that change is going to go down and if we've had any "early warnings"
16:00:21 <samccann> ok we can continue to discuss options but we are at the 1 hr mark
16:00:36 <samccann> so gonna end meeting unless anhyone else has something?
16:01:27 <samccann> #endmeeting