14:30:53 <acozine> #startmeeting Documentation Working Group aka DaWGs
14:30:53 <zodbot> Meeting started Tue Apr  7 14:30:53 2020 UTC.
14:30:53 <zodbot> This meeting is logged and archived in a public location.
14:30:53 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:30:53 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:30:53 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
14:31:01 <acozine> who's around?
14:31:11 <cbudz> greetings
14:31:19 <acozine> welcome cbudz!
14:31:24 <acozine> #chair cbudz
14:31:24 <zodbot> Current chairs: acozine cbudz
14:31:50 * samccann waves
14:32:17 <acozine> #chair samccann
14:32:17 <zodbot> Current chairs: acozine cbudz samccann
14:32:53 <acozine> nobody here but us chickens?
14:35:23 * samccann hears only crickets
14:35:34 * samccann and neighbor trimming a hedge
14:35:35 * felixfontein is around partially
14:35:41 <acozine> oof, i just looked up the origin of that phrase, and apparently it was originally used in a racist joke . . . I did not know that
14:35:56 <samccann> ooph! me either
14:36:16 <acozine> welcome, partial felixfontein
14:36:23 <cbudz> yikes
14:36:29 <cbudz> I also wasn't aware
14:36:30 <acozine> I can't make you a footstool, so . . .
14:36:34 <acozine> #chair felixfontein
14:36:34 <zodbot> Current chairs: acozine cbudz felixfontein samccann
14:36:40 <felixfontein> which phrase do you mean?
14:36:45 <acozine> https://www.waywordradio.org/us-chickens/
14:37:07 <felixfontein> oops
14:37:15 <felixfontein> I think I only heard it here so far :D
14:38:19 <acozine> there's an old blues song with that title too: https://en.wikipedia.org/wiki/Ain%27t_Nobody_Here_but_Us_Chickens
14:40:02 <acozine> felixfontein: I'll try to stick to standard English and not teach you phrases you might regret using
14:41:54 <acozine> #topic docs priorities for April
14:42:11 <felixfontein> acozine: thanks :D
14:42:38 <samccann> what I had listed in April priorities:
14:42:45 <samccann> - docs pipeline from collections
14:43:02 <samccann> - updating existing docs to reflects NWO and collections
14:43:21 <samccann> - set the collection/ACD release note/changelog strategy
14:43:37 <samccann> (as the currently burning fires).  Did I miss anything?
14:44:27 <acozine> I think that covers it
14:44:58 <acozine> samccann: do we have a ticket for the update-existing-docs work?
14:45:13 <acozine> it would be great if folks would add comments to it with pages that need updating
14:45:33 <samccann> #info - top priorities - the docs pipeline to get collection module docs into docs.ansible.com, update existing docs to reflect collections, set the strategy for collection/ACD changelogs
14:45:54 <acozine> we know some of the pages that need changes to reflect the collections ecosystem, but there may be a lot more
14:45:55 <samccann> there are more than one I think acozine... I'll dig them up and add them here as I find 'em
14:46:13 <acozine> thanks samccann!
14:50:37 <samccann> #info following links relate to documentation needs for updates based on collections:
14:50:51 <samccann> #link https://github.com/ansible/ansible/issues/67939
14:51:16 <samccann> #link https://github.com/ansible/ansible/issues/68594
14:52:01 <samccann> #link https://github.com/ansible/ansible/issues/67486
14:52:27 <samccann> #link https://github.com/ansible/ansible/issues/67484
14:53:05 <samccann> https://github.com/ansible/ansible/issues/67621
14:53:12 <samccann> dagnammit
14:53:15 <samccann> #link https://github.com/ansible/ansible/issues/67621
14:53:31 <samccann> and I feel like I'm missing one that actually had some good details in the comments on what needed to change.
14:55:03 <acozine> #link https://github.com/ansible/ansible/issues/60282
14:55:08 <acozine> maybe that one? ^^^
14:55:11 <samccann> #info some more docs requests appearing here - https://github.com/ansible-collections/overview/issues
14:55:37 <samccann> #link https://github.com/ansible/ansible/issues/60282
14:55:44 <samccann> yes that's the one I was remembering!  whew
14:56:16 <samccann> lots to do and we should put maybe P3 labels on all of them so they are easier to find (or P2 if we are committed to resolving them before release time)
14:56:37 <acozine> I think this search returns all of them: https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+label%3Adocs+collection+in%3Atitle
14:57:03 <acozine> oops, no it does not
14:57:39 <samccann> #info use this to potentially find more - https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+label%3Adocs+collection+in%3Atitle
14:57:59 <samccann> well we have p1, p2, and p3 as possible priority labels and we should start using them i think
14:58:12 <acozine> sounds good to me
14:58:17 <samccann> p1 and p2 as I recall means 'will block release'
14:58:23 <acozine> yep
14:58:53 <samccann> and P3 doesn't block.  So maybe this week we decide on the priority and then apply said labels
14:59:24 <bcoca> p3 is 'pool of stuff to do if your boss didnt tell you to do anything else first'
14:59:47 <samccann> HAHAHA
14:59:56 <samccann> we also could use the collection label
15:00:21 <acozine> #chair bcoca
15:00:21 <zodbot> Current chairs: acozine bcoca cbudz felixfontein samccann
15:00:23 <samccann> though others could use that for something that is collection coding with a minor doc impact so *shrug*
15:00:58 <acozine> only the bot and "members" of the ansible repo can put labels on issues
15:01:40 <acozine> so I think we're okay to use "label:docs label:collections" to mark these so we can find them more easily
15:01:45 <bcoca> its been a 'github feature' that hs been requested for a long time, 'others' can set up some labels via bot , but very limited
15:01:53 <acozine> p1-p2-p3 would also be fine
15:03:23 <samccann> my nickel is we use the collections label for now. If it gets messy, we can P1,P2 etc
15:03:43 <acozine> samccann: sounds good
15:04:54 <samccann> #agreed find and label docs issues that are for collections with the collection label
15:04:57 <acozine> I added the collections label to the ones I had open
15:05:02 <acozine> from your list above
15:05:40 <acozine> if anyone finds an issue or PR that should be labelled `collections` - if you can't add the label yourself, please post a link here and we will add it
15:06:06 <samccann> kewl
15:06:51 <acozine> #topic follow-up on release notes strategy
15:07:04 <acozine> #link https://github.com/ansible-collections/overview/issues/18#issuecomment-608473331
15:07:47 <samccann> I feel like we aren't getting enough voices deciding this one. And there will be wailing and gnashing of teeth if we just say' we will do option X'
15:08:07 <acozine> agreed
15:08:21 <cbudz> can we list some 'critical decision makers' on this topic?
15:08:28 <samccann> but we've had it on the agenda for weeks and we have had a handful of peeps with opinions. Just not sure how to put the final nail in this one to say decision made
15:08:55 <acozine> we can't make everybody happy all of the time, but it would be good to have a bit more feedback . . . I'm just not sure how to get it
15:09:10 <bcoca> i would say you have several diff discussions in one
15:09:11 <cbudz> What's the best venue to braodcast?
15:09:23 <samccann> gundalow are you around for a quick chat ?  ^^
15:09:45 <bcoca> you CAN have changelog fragment workflow for collections, but that might not be tied with ACD requiresments for docs (final product is easier for that) .. but 'community managed collections' might want the std anyways
15:09:48 <gundalow> Hi
15:09:49 <samccann> I'm pretty dang sure I've put it here and on #ansible-devel and #ansible-community multiple times...
15:10:00 <bcoca> i would try to keep those requirements sep, as much as they do influence each other
15:10:24 <samccann> hey gundalow - the question is - how do we make a final decision on the changelogs?  Who has to say 'yes' to one of the options to say the decision is made/final and someone can start coding if necessary?
15:10:45 <gundalow> Specific call to actions
15:10:45 <gundalow> List of people we'd like to review
15:10:45 <gundalow> Ping it round reddit (different eyes)
15:11:46 <samccann> So a 'speak now or forever hold your whining' round seems in order
15:11:46 <felixfontein> I guess most options (except maybe the "simply link to changelogs") needs some work done by someone on ACD side, so the people who have to implement it should have a voice in that decision too
15:11:58 <samccann> yeah agreed on that one
15:12:38 <gundalow> Do we want people to vote by commenting on the issue?
15:12:48 <gundalow> I can ask the existing collection owners
15:13:10 <samccann> yeah that would be great!
15:13:15 <acozine> +1
15:13:36 <samccann> I can bug the security and network teams in Ansible to put up a vote or two
15:13:45 <samccann> I can post on reddit as well
15:14:34 <gundalow> samccann: that would be great, thank you
15:14:43 <samccann> #action gundalow to ask collection owners to vote on https://github.com/ansible-collections/overview/issues/18#issuecomment-608473331
15:15:05 <samccann> #action samccann to post request for comments to reddit on https://github.com/ansible-collections/overview/issues/18#issuecomment-608473331 as well
15:15:44 <samccann> #info we will send out a final call to action with a goal to get people to vote on an option for the changelog and make a final decision
15:16:16 <samccann> Are there specific people who have to agree before we can finalize?  I think we got the internal RH PM to agree that even a simple list of links is okay
15:16:39 <samccann> and we can reach out to the person who would end up coding this for their vote for sure. Just not sure who else HAS to agree?
15:17:18 <samccann> (not saying we go with just a list of links, but just that it or anything better seems to be okay from that perspective)
15:17:38 <acozine> I think we have support for any solution that works for the community
15:18:19 <acozine> I don't think there's anyone internally who 1. must agree and 2. has not already spoken up
15:19:32 <acozine> anything else on changelogs?
15:20:06 <acozine> next agenda item is . . .
15:20:25 <acozine> #topic provide a way for collection developers to create .rst files from modules??
15:20:54 <acozine> I think this is about allowing collection devs to build the docs for their collections locally . . .
15:21:19 <samccann> Well it covered a few things:
15:21:30 <samccann> - create docs locally (for developers)
15:22:01 <samccann> - create docs 'somehow' for users since galaxy UI won't display them for some time (this includes collections not part of ACD)
15:22:22 <samccann> - create docs 'somehow' for people with private collections
15:22:33 <acozine> ah, thanks samccann
15:22:58 <samccann> #info details on the original discussion are here - https://github.com/ansible/community/issues/521#issuecomment-606234088
15:23:34 <acozine> we've talked about packaging up the theme and other Sphinx stuff for use in collections
15:24:58 <samccann> i'm still not convinced we need to do that much
15:25:22 <acozine> good, because I'm not convinced we have the bandwidth to do that much ;-)
15:25:23 <samccann> i do think we need to have a tool to create .rst files. From there, I think the collection owner etc can 'do their own thing' so to speak
15:25:53 <acozine> ah, so package up the YAML-to-rst part of the current docs pipeline
15:26:16 <acozine> or at least make it easy to copy into a collection and use there
15:26:54 <acozine> that seems do-abler
15:27:02 <acozine> heh, do-able
15:27:53 <samccann> doabler is good :-)
15:28:22 <acozine> this is how the language evolves
15:28:27 <samccann> should we just move this into an issue on ansible/ansible (with the link to that comment for background info?)
15:28:34 <acozine> I like that idea
15:29:10 <samccann> #action samccann to create issue on ansible/ansible to create a tool/way for collection dev/users to get .rst files from the module docstrings
15:29:29 <acozine> excellent!
15:29:35 <acozine> and we have one minute for . . .
15:29:41 <acozine> #topic open floor
15:31:02 <acozine> it's so quiet in here this week!
15:31:20 <acozine> after last week's marathon session
15:32:06 <samccann> haha
15:32:06 <acozine> as always, agenda items are welcome, add a comment to https://github.com/ansible/community/issues/521 at any time
15:32:21 <acozine> #info agenda items welcome on https://github.com/ansible/community/issues/521
15:32:31 * acozine is learning a couple of IRC tricks at last
15:32:45 <samccann> woot woot!!
15:33:02 <acozine> thanks bcoca cbudz felixfontein gundalow samccann
15:33:14 <acozine> #endmeeting