15:01:56 <samccann> #startmeeting Ansible documentation Working Group aka DawGs meeting
15:01:56 <zodbot> Meeting started Tue Jun  1 15:01:56 2021 UTC.
15:01:56 <zodbot> This meeting is logged and archived in a public location.
15:01:56 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:56 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:56 <zodbot> The meeting name has been set to 'ansible_documentation_working_group_aka_dawgs_meeting'
15:01:58 <gundalow> s/r/t
15:02:03 * gundalow waves
15:02:03 <acozine> o/
15:02:07 <samccann> #chair gundalow acozine
15:02:07 <zodbot> Current chairs: acozine gundalow samccann
15:02:23 <dmsimard> \o
15:02:43 <acozine> #chair dmsimard
15:02:43 <zodbot> Current chairs: acozine dmsimard gundalow samccann
15:02:55 * dericcrago waves
15:03:15 <abadger1999> Ola
15:03:18 <acozine> abadger1999: bcoca dericcrago aminvakil briantist cyberpear felixfontein you folks talking docs today?
15:03:19 <acozine> heh
15:03:24 <acozine> you two beat me to it
15:03:28 <acozine> #chair dericcrago abadger1999
15:03:28 <zodbot> Current chairs: abadger1999 acozine dericcrago dmsimard gundalow samccann
15:03:59 <felixfontein> hi!
15:04:07 <acozine> baptistemm: tadeboro on my display your nicks are greyed out, but if you're around, join us!
15:04:11 <acozine> #chair felixfontein
15:04:11 <zodbot> Current chairs: abadger1999 acozine dericcrago dmsimard felixfontein gundalow samccann
15:04:36 * cyberpear listens in, partly here
15:05:09 <acozine> anyone else who is listening/watching, if you want to participate, you are very welcome!
15:05:19 <acozine> just wave like this: `p/`
15:05:22 <acozine> heh
15:05:29 <acozine> I mean like this: `o/`
15:05:42 <acozine> cyberpear: do you want to be furniture?
15:05:51 <aminvakil> hi!
15:06:03 <acozine> #chair aminvakil
15:06:03 <zodbot> Current chairs: abadger1999 acozine aminvakil dericcrago dmsimard felixfontein gundalow samccann
15:06:08 <acozine> hey aminvakil, welcome!
15:06:49 <aminvakil> i'm happy i could make it this week
15:06:53 <acozine> full disclosure . . . those of us at RH in the US had a four-day weekend (Friday-Sat-Sun-Monday)
15:07:13 <acozine> and i don't know about others, but my brain isn't fully back at work yet
15:07:40 <acozine> so it may be a slightly scattered meeting today
15:07:52 <samccann> heh
15:08:51 <acozine> official agenda: https://github.com/ansible/community/issues/579#issuecomment-848064836
15:08:54 <acozine> #topic opening chatter
15:09:06 <acozine> I even forgot to set a topic
15:09:15 <aminvakil> :)
15:09:18 <samccann> it's a virtual monday here
15:10:16 <felixfontein> ah right, you had some holiday yesterday and on Friday
15:10:27 <gundalow> #info Contributors Summit is next week https://hackmd.io/0lOyfyEpQ1uKimC4mD6xdw 07:00 - 15:00 UTC
15:10:27 <felixfontein> long weekend is looong :)
15:11:09 <acozine> it was lovely - lots of time outside, the weather was good here
15:11:15 <dmsimard> any docs topics for summit next week ?
15:11:39 <acozine> #topic Contributors' Summit
15:11:56 <dmsimard> could maybe briefly talk about the core/community split and improvements (like breadcrumbs)
15:12:10 <acozine> sure, we could do that
15:12:43 <acozine> this Summit is in an earlier time-slot, right?
15:13:05 <acozine> do you want someone from docs to present?
15:13:09 <acozine> dmsimard: ^^^
15:13:43 <dmsimard> starting at 7 UTC will make it difficult for folks in north america to be there early on
15:13:47 <acozine> if so, I think we'll either need to recruit someone from DaWGs in Europe or take the last possible presentation time
15:14:13 <acozine> when does it end this time around?
15:14:24 <gundalow> 07:00 - 15:00 UTC
15:14:37 <gundalow> So it will have ended 14 minutes ago
15:15:02 <abadger1999> Heh.  I'll be getting up when it ends ;-)
15:15:10 <acozine> gundalow: thanks, so we could definitely do something in the last hour or last two hours
15:15:23 <felixfontein> ah, it's starting in the morning this time?
15:15:25 <felixfontein> good to know :)
15:15:26 <acozine> even I am usually at my desk by 14:00 UTC
15:15:36 <gundalow> or stay up late and present first :P
15:15:48 <dmsimard> felixfontein: the plan is to make this one a bit more friendly to EMEA/APAC timezones
15:15:54 <gundalow> felixfontein: yup, we wanted to mix up the TZ a bit
15:15:58 <acozine> yeah, it's a great idea
15:16:24 <acozine> (having Summit at EMEA/APAC-friendly times)
15:16:57 * acozine thinks about what time that start time would be . . .
15:17:22 <dmsimard> https://whena.re/ansible-community is helpful to visualize timezones :)
15:17:33 <acozine> that would be 02:00 for me, so probably not a good idea
15:17:52 <felixfontein> that would be pretty late
15:18:02 <acozine> I can be coherent at midnight, but anything after that gets . . . funky
15:18:52 <samccann> heh... you become... decoherent???
15:19:09 <acozine> heh, yep - bits start flying off around the edges
15:19:18 <samccann> lol
15:19:26 <acozine> especially brain bits ;-)
15:19:33 <dmsimard> acozine: I'll add a docs topic on the summit agenda for now, we haven't worked out the exact schedule yet but will be mindful of TZ
15:19:43 <acozine> dmsimard: thanks
15:21:49 <gundalow> Whats next?
15:22:09 <acozine> heh
15:22:32 <acozine> #topic devel docs for hte package
15:22:47 * acozine is not feeling creative, will just go down the agenda items today
15:23:26 <acozine> our intention is to pull the most recent version of each included collection to document `devel` for Ansible the package
15:23:41 <acozine> (most recent version uploaded to Galaxy, that is)
15:24:35 <acozine> it's been a while since we talked about this, and I don't remember where we are with it
15:24:49 <gundalow> How many times a day do you think that might happen?
15:25:18 <samccann> hmm. i'm stale on it as well, but I thought it would just be part of the nightly docs build
15:25:26 <acozine> we currently publish `devel` to docs.ansible.com four times a day
15:25:28 <samccann> which is more than nightly, but still
15:25:31 <acozine> but we can change the frequency
15:26:01 <acozine> we already have an automated pipeline for publication
15:26:10 <abadger1999> I probably am responsible for this.  I think there's some coding to do.
15:26:19 <acozine> the piece we're missing is adding collections beyond ansible.builtin
15:26:39 <abadger1999> I recall there being a ticket with the pieces we need but I don't seem to see it right now.
15:26:49 * acozine looks around
15:27:48 <abadger1999> I found a hackmd: https://hackmd.io/E5a0dw0tTDCteQVVk4VvJw
15:28:33 <samccann> cool
15:28:39 <acozine> awesome, thanks abadger1999
15:28:44 <samccann> not having any luck finding an issue that documents what we need so that might be it?
15:29:14 <acozine> so it looks like we don't need to discuss it or vote or anything
15:29:52 <samccann> #info details on the ideas are at https://hackmd.io/E5a0dw0tTDCteQVVk4VvJw
15:29:59 <acozine> https://github.com/ansible-community/antsibull/issues/54
15:30:23 <samccann> #info tracking issue for antsibull work needed - https://github.com/ansible-community/antsibull/issues/54
15:30:26 <acozine> it was even linked into the agenda!
15:30:37 <abadger1999> Heh :-)
15:30:59 <samccann> #info goal is to pull the most recent version on galaxy for each included collection to document `devel` for Ansible the package
15:31:08 <abadger1999> Okay, I have free time this week (/me crosses fingers, knocks on wood) so I'll work on this before next meeting
15:31:32 <samccann> #action abadger1999 to take some time this week if possible to delve further on this one
15:32:12 <acozine> #topic template for using collection /docs/ folder
15:32:30 <acozine> hey, we may be able to close this topic out!
15:32:36 <acozine> now that we've merged https://github.com/ansible-community/antsibull/pull/255
15:32:41 <acozine> are we done?
15:32:44 <samccann> hmmm
15:32:49 <samccann> i have questions ;-)
15:33:15 <samccann> Based on The Powers That Be - there is also a somewhat conflicting drive to move scenario guides into /docs folder directly as markdown
15:33:49 <acozine> I think that is up to the collection maintainers
15:33:53 <samccann> So, how do we decide what moves to .md and what moves to rst?
15:34:25 <samccann> Okay, if that's our decision, we should document it somewheres
15:35:00 <abadger1999> I think if someone wants it on docs.ansible.com, it's going to have to be rst.
15:35:11 <felixfontein> I would first move the RSTs, and then let collection maintainers decide whether they want MD instead, together with RST, or whatever
15:35:13 <samccann> yes, but we have to make the decision clear
15:35:19 <felixfontein> abadger1999: exactly
15:35:50 <samccann> like go to md if you want it in AH/galaxy-ng. go to rst if you want it back on docs.ansible.com AND your collection is in Ansible.
15:35:58 <samccann> And do both if you want it in both places
15:36:17 <abadger1999> and we probably don't want to touch it if it's directly in docs either (since we don't know how to tie that al together)
15:36:32 <samccann> not sure what you mean ^^ ?
15:36:53 * acozine thinks about where to document those guidelines
15:37:06 <abadger1999> That just references the reasons we deided on a subfolder.
15:37:17 <samccann> ah gotcha
15:37:36 <samccann> acozine - we have a section in the collections structure page that mentions the /docs folder. We could add the details there
15:37:46 <samccann> and it probably also needs to go out in the bullhorn
15:38:01 <samccann> assuming we are ready to let people loose with all this?
15:38:14 <acozine> ah, right
15:38:15 <acozine> https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#docs-directory
15:38:29 <samccann> #info the PR for this is merged - https://github.com/ansible-community/antsibull/pull/255
15:38:33 <acozine> I think we are ready
15:38:52 <acozine> my guess is that most collection owners won't create "extra" docs
15:39:06 <samccann> #action document how to use the collection /docs folder (.md or .rst) at https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#docs-directory
15:39:13 <acozine> my hope is that only active maintainers will create "extra" docs
15:39:29 <felixfontein> community.docker is already released with the scenario guide added, so we can soon merge the corresponding PR in ansible/ansible
15:39:39 <acozine> felixfontein: awesome
15:39:48 <felixfontein> community.crypto and community.general will also come with extra docs (that (mostly) wasn't in ansible/ansible before)
15:40:00 <samccann> busy busy bee!
15:40:24 <samccann> #info first candidates to exercise this may be community.docker, community.crypto and community.general
15:40:29 <acozine> felixfontein: is there already a remove-docker-docs PR in ansible/ansible?
15:41:50 <felixfontein> yes
15:42:01 <samccann> cyb-clock-clone has just woken up. We are 40 minutes into the meeting and 10 min into this topic
15:42:13 <felixfontein> https://github.com/ansible/ansible/pull/74736
15:42:22 <felixfontein> good morning cyb-clock-clone :)
15:42:29 <samccann> #info remove docer docs pr is https://github.com/ansible/ansible/pull/74736
15:42:38 <samccann> #undo
15:42:38 <zodbot> Removing item from minutes: INFO by samccann at 15:42:29 : remove docer docs pr is https://github.com/ansible/ansible/pull/74736
15:42:48 <samccann> #info remove docker docs pr is https://github.com/ansible/ansible/pull/74736
15:43:06 <samccann> so can we 'test' this by staging that PR?
15:43:07 <acozine> so as soon as we have a package release that includes the version of community.docker that has those docs, we can merge
15:43:27 <samccann> ah that might answer the question.
15:43:36 <acozine> or as soon as we have `devel` collection docs, whichever comes first
15:43:41 <samccann> #info so as soon as we have a package release that includes the version of community.docker that has those docs, we can merge
15:44:54 <samccann> So there are no 'next steps' for this until then?
15:45:06 <felixfontein> I guess we can already merge, and only merge the backport once Ansible 4.1.0 is out
15:45:20 <acozine> ah, true
15:45:30 <acozine> those docs would still show up in `latest`
15:45:37 <samccann> will it show up on `devel'? or not until Ansible 4.1 is out
15:46:11 <acozine> the docs will show up in `latest` under Scenario Guides
15:46:46 <felixfontein> I guess the link will be broken in devel until 4.1.0 is out, or until devel docs are working as expected (whatever comes first)
15:46:56 <acozine> will show up in `latest` under the community.docker collection when 4.1 is released, assuming it contains that version of the collection
15:47:03 <samccann> 4.1.0 is due out in a week fwiw
15:47:11 <acozine> I'm happy to merge, or not
15:47:54 <samccann> so if we merge, the scenario guide for docker disappears on devel but doesn't show up again until 4.1.0 goes out?
15:48:15 <felixfontein> samccann: probably yes
15:48:16 <acozine> it won't show up in devel until we have all collections in devel
15:48:28 <felixfontein> so maybe let's wait with merge until the beginning of next week
15:48:30 <acozine> (in its new location)
15:48:34 <acozine> sounds good
15:49:05 <felixfontein> the AWS guide(s?) will probably have to wait longer
15:49:13 <acozine> maybe
15:49:29 <samccann> there was a request early on to talk about the core/community split and we only have 10 min left
15:49:49 <acozine> thanks cyb-clock!
15:50:10 <acozine> anything else on collection docs, or other topics we've covered so far?
15:50:36 * acozine waits a beat
15:50:54 <acozine> #topic open floor
15:51:26 <acozine> samccann: I think the "let's talk about the core/community split" request was for someone to talk about it at hte contrib summit
15:51:36 <dmsimard> it was my intent, yeah
15:52:13 <felixfontein> if someone has time to glance over https://github.com/ansible-collections/community.general/pull/2680, I'd be happy for feedback :)
15:52:42 <samccann> oh haha!
15:54:03 <acozine> felixfontein: thanks for the pointer, I am still not in the habit of checking for PRs in the collections repos
15:55:30 <acozine> documenting filters is tricky because experienced users want to search by the name of the filter or by the technical term they know, but beginners only know they have a problem they need to solve, and they need a way to connect their problem to the filter name
15:55:56 <acozine> maybe we need something like The Ansible Beginner's Guide to Filters
15:56:34 <felixfontein> true
15:57:11 <aminvakil> acozine: +1
15:57:41 <acozine> I'll take a look in more detail, but what you have there looks good for the experienced-user case
15:58:56 <acozine> what else do folks have for the open floor?
15:59:02 <acozine> PRs ready for feedback?
15:59:03 <felixfontein> acozine: that's a good start, because right now there are no docs at all, and some docs are already a lot better than no docs ;)
15:59:07 <acozine> issues needing review?
15:59:11 <acozine> felixfontein: very true
16:00:07 <acozine> we can definitely merge then add more "hand-holding" docs later
16:00:29 <acozine> thanks for documenting the filters in community.general!
16:01:25 <acozine> we should add a link into the main filters page as well
16:01:32 <acozine> I'll add that to my list
16:02:20 <felixfontein> before I can merge that PR, there's some work needed with antsibull first (or the syntax highlighter repo, whatever comes first)
16:02:52 <acozine> ah, yes, the CI failure on the ansible highlighter
16:03:39 <acozine> thanks for fixing that for Sphinx 4, by the way
16:03:43 <samccann> is there something we want to info about that?
16:04:14 * acozine thinks
16:04:53 <acozine> #info filter docs PR for community.general requires a change to either antsibull or the ansible syntax highlighter
16:05:11 <acozine> #info https://github.com/ansible-collections/community.general/pull/2680/files
16:05:25 <acozine> okay, we're five minutes past the hour
16:05:30 <acozine> other topics for the open floor?
16:06:31 <felixfontein> abadger1999: what do you prefer, merging https://github.com/ansible-community/antsibull/pull/278 and releasing a new antsibull version with it, or releasing https://github.com/ansible-community/sphinx_ansible_highlighter/ first (and using it to make the tests pass by installing it)?
16:06:37 <acozine> #info An Ansible Beginner's Guide to Filters might be a good addition to the dev-focused filter docs
16:07:39 <felixfontein> +1
16:08:28 <acozine> maybe abadger1999 went to get some breakfast?
16:08:32 <abadger1999> felixfontein: I think merging 278.  Can you see any drawbacks to merging that?
16:10:17 <felixfontein> abadger1999: the main drawback is that the entrypoints are added, which will be removed again once the lexer is finally moved to the other repo
16:10:28 <felixfontein> besides that, I don't see any
16:10:59 <abadger1999> I think it's nice to get something that works out quickly.
16:11:05 <felixfontein> I agree :)
16:11:20 <abadger1999> Cool.  I'll merge and release then.
16:11:27 <acozine> \o/
16:11:50 <acozine> we do document the `path.join` filter at least, and maybe others, in https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html#managing-file-names-and-path-names
16:12:44 <felixfontein> acozine: the `path_join` filter in c.g is mainly a shim which allows to use it with Ansible 2.9 as well :)
16:12:47 <acozine> don't know if we want to maintain centralized docs for "all filters" or not moving forward
16:12:59 <felixfontein> the main filter is in ansible-base and ansible-core
16:13:04 <acozine> ah, gotcha
16:13:36 <felixfontein> this section: https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html#selecting-json-data-json-queries I basically copied over, since the filter is part of c.g
16:14:11 <acozine> yeah, I hadn't thought about how to document filters in the collections ecosystem, really
16:14:32 <felixfontein> random_mac is also part of c.g, I only noticed that it was documented there already after writing some docs, so I only copied parts of it
16:14:38 <acozine> heh
16:15:45 <acozine> so maybe the dev-focused docs move to collections and the page in ansible/ansible becomes more beginner-focused over time . . .
16:15:57 <acozine> for now, duplicating seems like the best option
16:16:01 <acozine> filters don't change much
16:16:10 <acozine> so it isn't a big maintenance burden
16:16:42 <acozine> okay, we're now fifteen minutes over the hour
16:16:44 <samccann> cyb-clock-clone sez we are 1hr 15 min into the meeting and 10 minutes into current topic
16:16:47 <acozine> heh
16:16:51 <samccann> :-)
16:16:59 * acozine likes `cyb-clock-clone`
16:17:24 <acozine> I'm gonna call it a week
16:17:56 <gundalow> abadger1999: When you get a chance could you please backport https://github.com/ansible/ansible/pull/74775 (probs to 2.9)
16:18:06 <acozine> thanks abadger1999  aminvakil dericcrago dmsimard felixfontein gundalow samccann and all lurkers!
16:18:07 <gundalow> ^ `s/freenode/libera.chat/g`
16:18:28 <acozine> gundalow: ???
16:18:50 <acozine> where do you see freenode mentioned?
16:19:10 <acozine> ahh, I see
16:19:13 <gundalow> acozine: hopefully nowhere now that the above PR is merged :)
16:19:14 <acozine> that PR makes the change
16:19:20 <gundalow> though thats' only devel
16:19:25 <gundalow> (sorry I didn't give context)
16:19:28 <acozine> heh
16:19:37 <gundalow> :)
16:19:41 <acozine> okay, thanks folks
16:19:55 <gundalow> abadger1999: oh and maybe manually build 2.9+ docs (unless that happens daily)
16:19:58 <gundalow> Nothing else form me
16:20:00 <abadger1999> Oof.  Yeah, I can.  I didn't think about needing to do that. (each backport is probably only a bit smaller than  patching it for devel)
16:20:02 <gundalow> from
16:20:04 <acozine> agenda items welcome for next week (or any week)
16:20:12 <gundalow> abadger1999: Thanks :)
16:20:26 <acozine> to add an agenda item, add a comment to https://github.com/ansible/community/issues/579
16:20:37 <acozine> thanks again, see you all next week!
16:20:40 <acozine> #endmeeting