15:01:57 <acozine> #startmeeting Documentation Working Group aka DaWGS
15:01:57 <zodbot> Meeting started Tue Jun 15 15:01:57 2021 UTC.
15:01:57 <zodbot> This meeting is logged and archived in a public location.
15:01:57 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:57 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:57 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:02 <acozine> #topic opening chatter
15:02:05 <acozine> who's around?
15:02:11 <lmodemal> DING DING DING!  DaWGs (documentation working group meeting) happening now https://github.com/ansible/community/issues/579
15:02:35 <samccann> \o
15:02:45 <lmodemal> o/
15:03:04 <acozine> andersson007_: bcoca dericcrago dmsimard gundalow samccann aminvakil briantist felixfontein tadeboro Xaroth zbr you folks chatting docs?
15:03:09 <acozine> #chair samccann lmodemal
15:03:09 <zodbot> Current chairs: acozine lmodemal samccann
15:03:25 * dericcrago waves
15:03:34 <acozine> #chair dericcrago
15:03:34 <zodbot> Current chairs: acozine dericcrago lmodemal samccann
15:03:36 <Xaroth> o7 I'm around.. ish... but about to head home from the office.
15:03:58 * gundalow waves
15:04:05 <acozine> Xaroth: cool, do you want to be furniture? (be made a "chair')
15:04:09 <acozine> #chair gundalow
15:04:09 <zodbot> Current chairs: acozine dericcrago gundalow lmodemal samccann
15:04:11 <felixfontein> o/
15:04:15 <Xaroth> sure.
15:04:15 <acozine> #chair felixfontein
15:04:15 <zodbot> Current chairs: acozine dericcrago felixfontein gundalow lmodemal samccann
15:04:21 <acozine> #chair Xaroth
15:04:21 <zodbot> Current chairs: Xaroth acozine dericcrago felixfontein gundalow lmodemal samccann
15:05:27 <acozine> official agenda begins with: https://github.com/ansible/community/issues/579#issuecomment-860165171
15:05:47 <acozine> busy week, this week!
15:06:06 <felixfontein> indeed!
15:06:19 <acozine> #topic moving docker scenario guide
15:06:21 <acozine> https://github.com/ansible/ansible/pull/74736
15:06:46 <felixfontein> I think that's ready now, since the scenario guide is now showing on the docsite
15:06:59 <felixfontein> except that it doesn't show on the devel docs because of a bug in the devel docs build (see https://github.com/ansible/ansible/pull/74987)
15:07:14 <acozine> ah
15:07:25 <felixfontein> so that PR doesn't produce the correct result on devel (on devel there will be no docker guide), but it does on stable-2.11
15:07:26 <acozine> because devel docs are pulling in the wrong list of collection versions
15:07:36 <felixfontein> yes, they are pulling in the ones from Ansible 4.0.0
15:07:42 <acozine> heh, that's backwards
15:07:49 <felixfontein> yes :)
15:08:07 <acozine> okay, so the scenario guide shows up here: https://docs.ansible.com/ansible/latest/collections/community/docker/index.html#plugins-in-community-docker
15:08:13 <briantist> half here as usual 😅
15:08:24 <acozine> briantist: cool, you want to be furniture?
15:08:32 <briantist> sure why not
15:08:38 <acozine> #chair briantist
15:08:38 <zodbot> Current chairs: Xaroth acozine briantist dericcrago felixfontein gundalow lmodemal samccann
15:08:53 <acozine> it's a big table, glad to see so many seats in use!
15:09:19 <samccann> :-)
15:09:36 <acozine> felixfontein: thanks for the PR, it's great to see scenario guides moving into collections!
15:09:54 <samccann> so felixfontein - so seems like we merge both PRs and then backport the docker one to stable-2.11?
15:10:23 <acozine> any comments, questions, concerns on this one?
15:10:31 <acozine> I'm happy to merge right now to devel
15:10:43 <samccann> +1 go for it
15:10:56 <samccann> once you merge, I can stage devel just to see if anything goes wonky
15:10:58 <acozine> the backport can't be merged until next week, due to the core release schedule, but we can have it ready
15:11:35 <acozine> we'll need to merge the other PR too, the one that fixes the collections-version-list
15:11:36 <felixfontein> samccann: yes
15:11:48 <felixfontein> (the devel docs PR does not need to be backported, since devel docs are not build from stable-x branches)
15:11:49 <samccann> #info docker PR to remove old scenario guide and put in a stub https://github.com/ansible/ansible/pull/74736/files
15:12:29 <felixfontein> (it's probably best to trigger CI once more before merging though, just in case)
15:12:39 <samccann> #info depends on this devel PR  to work on devel - https://github.com/ansible/ansible/pull/74987
15:13:20 <acozine> oops, I missed the `stale_ci` label
15:13:22 <acozine> drat
15:13:30 <felixfontein> ah well, it shouldn't be that bad
15:13:36 <felixfontein> I'll keep an eye on the commit tests
15:13:56 <felixfontein> if they pass, everything's fine
15:14:06 <acozine> oh, for some reason the bot removed the stale ci label
15:14:07 <felixfontein> (https://github.com/ansible/ansible/runs/2830886533)
15:14:28 <felixfontein> that's... interesting
15:14:33 <acozine> oh, when you force-pushed 8 days ago
15:14:36 <acozine> CI ran then
15:15:01 <felixfontein> ah, I did a force push... missed that :D
15:15:10 <acozine> phew
15:15:26 <felixfontein> I'll watch https://dev.azure.com/ansible/ansible/_build/results?buildId=17995&view=results anyway and look for failures
15:15:55 <acozine> sounds good, thanks
15:16:26 <samccann> are you merging the other one too? the devel fix?
15:16:32 <acozine> let's discuss
15:16:47 <acozine> #topic updating collection version list for devel docs
15:16:50 <acozine> https://github.com/ansible/ansible/pull/74987/files
15:17:13 <samccann> #link https://github.com/ansible/ansible/pull/74987/files
15:17:32 <samccann> cyb-clock-clone sez we are 17 minutes into the meeting
15:17:57 <felixfontein> it should be pretty safe to merge this, since it only affects devel docs builds (and that part will get replaced by 'the real thing' hopefully soon anyway :) )
15:18:03 <acozine> so in preparation for Ansible 5 in a few months, we added https://github.com/ansible-community/ansible-build-data/tree/main/5
15:18:36 <acozine> eventually that will track the list of collections included in Ansible 5, which will be based on ansible-core 2.12 aka the current devel branch
15:18:36 <felixfontein> yes, and right now it does not contain any .deps data - except a symlink ancestor.deps that's used for the changelog generation
15:18:56 <acozine> gotcha
15:19:23 <acozine> so the workaround here is to use ancestor.deps for the devel docs
15:19:51 <acozine> does that mean the collections section of the devel docs will be identical to the collections section of the latest docs, for now?
15:19:52 <felixfontein> no, the workaround is to ignore directories whose only .deps file is ancestor.deps :)
15:20:36 <felixfontein> but yes, with this workaround the collections section of the devel docs will identical to the collections section of the latest docs
15:20:40 <acozine> okay, I misunderstood the mechanism . . . did I understand the outcome correctly?
15:20:44 <acozine> gotcha
15:20:48 <felixfontein> (i.e. what the current code was supposed to do)
15:21:15 <acozine> and eventually we can use this model to build devel docs that differ from the latest docs
15:21:27 <acozine> differ by being more recent, I mean
15:21:33 <samccann> #info the workaround will ensure the collections section of the devel docs will be identical to the collections section of latest docs for now. Until we have real 'devel' collections docs
15:21:38 <acozine> right now they differ by being older
15:22:06 <felixfontein> yep
15:22:29 <acozine> samccann: can you run a build to the test site using the PR's branch?
15:22:33 <felixfontein> (in fact I also have PRs for the real devel, but they definitely need reviews by Toshio first :) )
15:22:54 <acozine> heh
15:23:23 <acozine> yeah, I'm clearly not the right person to review those, but others here might have useful reviews
15:23:25 <samccann> acozine yeah I can
15:24:30 <acozine> thanks!
15:24:49 <felixfontein> thanks!
15:25:28 <acozine> felixfontein: do you have links to the other PRs handy?
15:25:53 <acozine> since we set the topic to "fixing the devel collections docs" we can put those in the minutes
15:26:02 <samccann> hmm... jenkins only has package version 4 so I think I need to add 5 to test this pr
15:26:21 <acozine> nm, I see them
15:26:29 <acozine> https://github.com/ansible-community/antsibull/pull/282
15:26:38 <acozine> https://github.com/ansible/ansible/pull/74988
15:26:44 <acozine> reviews welcome on ^^^
15:27:13 <acozine> samccann: can't we just mark the run as `devel`?
15:27:20 <acozine> that's what we'll do in production
15:27:38 <acozine> we can't have a docset out there for `Ansible 5` . . .
15:27:47 <samccann> acozine - honestly I lost the plot. So I added 5, but yeah I'm running a 4 build as well
15:28:00 <acozine> sounds godd
15:28:06 <acozine> s/godd/good
15:28:15 <samccann> this is the manual package docs build. so nightly will just do 4 anyway
15:28:38 <samccann> #info reviews welcome on https://github.com/ansible-community/antsibull/pull/282 and https://github.com/ansible/ansible/pull/74988
15:28:49 <acozine> related issue is https://github.com/ansible-community/antsibull/issues/54
15:29:12 <samccann> #info related issue is https://github.com/ansible-community/antsibull/issues/54
15:30:06 * lmodemal Have to drop off for another meeting :)
15:30:26 <acozine> lmodemal: thanks for coming
15:30:30 <acozine> see you next week
15:31:13 <acozine> other thoughts on devel docs?
15:31:33 <acozine> I wonder how many people really use the devel docs
15:31:39 <acozine> I guess our traffic analysis would tell us
15:32:05 <samccann> I want to say it gets about 5% of the traffic latest gets? I can verify that
15:32:18 <acozine> that seems about right
15:33:04 <felixfontein> I wonder if it depends on what people look for
15:33:17 <acozine> most people are focused on using the current (or older) docs for whichever Ansible version they have installed
15:33:18 <felixfontein> for development stuff, I usually prefer to send people to devel since it's generally more up-to-date
15:33:19 <samccann> cyb-clock-clone sez we are 33 min into the meeting and 15 min into current topic
15:33:47 <acozine> felixfontein: yeah, that makes sense
15:33:49 <felixfontein> and for content authors (collection maintainers) the new devel will be interesting since you can look at your collection's docs before the next Ansible release
15:33:55 <samccann> yeah that feeds into the ideas of moving different docs around to be 'version independent' so to speak.
15:33:59 <felixfontein> (assuming you released your collection)
15:34:28 <acozine> heh, yep
15:34:50 <acozine> okay, we've done the immediately-actionable stuff from today's agenda
15:35:00 <acozine> and we have time for at least one more topic
15:35:24 <felixfontein> semantic markup?
15:35:40 <acozine> what do folks want to talk about? semantic markup? or community docs? or . . . ?
15:35:53 <acozine> #chair
15:35:53 <zodbot> Current chairs: Xaroth acozine briantist dericcrago felixfontein gundalow lmodemal samccann
15:35:59 <acozine> oops
15:36:01 <bcoca> just to get eyes on it https://github.com/ansible/ansible/pull/74914
15:36:04 <acozine> #unchair lmodemal
15:36:04 <zodbot> Current chairs: Xaroth acozine briantist dericcrago felixfontein gundalow samccann
15:36:27 <acozine> #chair bcoca
15:36:27 <zodbot> Current chairs: Xaroth acozine bcoca briantist dericcrago felixfontein gundalow samccann
15:36:29 <bcoca> ^ can create 'full example ini/env vars/varss.yml' for ansible configurations (base + plugins, base or specific plugins)
15:37:03 <bcoca> helpful in generating a more complete config/env var pages (which currently only reflect base)
15:37:20 <samccann> #info reviews welcome on https://github.com/ansible/ansible/pull/74914
15:37:54 <samccann> are we talking semantic markup or community docs personas?
15:37:54 <felixfontein> there's also https://github.com/ansible/ansible/pull/74963 btw which adds documentation capabilities for filter and test docs
15:38:27 <samccann> #info reviews also welcome on https://github.com/ansible/ansible/pull/74963 btw which adds documentation capabilities for filter and test docs
15:38:40 <acozine> dang, we should probably have put a topic change in there
15:38:41 <bcoca> 74963 still needs lots of work
15:38:53 <bcoca> config one is almost ready to merge
15:38:56 <felixfontein> yes, but there finally IS a PR for that :)
15:39:07 <bcoca> he, sorry for having made you wait for soo long
15:39:34 <acozine> #info the two PRs above expand the range of the generated technical docs (by extending config documentation and documenting filter and test plugins)
15:40:25 <acozine> bcoca: anything else you need beyond extra pairs of eyes?
15:40:41 <acozine> (for that PR, I mean . . .)
15:40:45 <bcoca> about 62 other PRs .. but the ones above are most relevant to docs
15:40:55 <acozine> heh
15:41:02 <acozine> okay, thanks for those!
15:41:04 <bcoca> ;-)
15:41:31 <acozine> #topic semantic markup
15:42:54 <acozine> quick summary: we'd like to use a standard markup for things like module options, variable values, and environment variables across all the Ansible documentation
15:43:13 <acozine> related PRs include:
15:43:39 <samccann> #info just fyi - devel docs get approx 4% of the traffic vs /latest/ docs and /ansible-core/ gets approx 1%
15:44:10 <acozine> cool, thanks for the details!
15:44:17 <acozine> https://github.com/ansible/ansible/pull/74937
15:44:19 <felixfontein> ah, thanks!
15:44:34 <acozine> https://github.com/ansible-community/antsibull/pull/281
15:44:48 <acozine> https://github.com/ansible-collections/community.dns/pull/23
15:44:56 <acozine> and
15:44:57 <acozine> √
15:44:59 <acozine> https://github.com/ansible/ansible/pull/73137
15:45:26 <felixfontein> samccann: did you manage to find out how key=value should be rendered?
15:45:44 <samccann> #info related PRs https://github.com/ansible/ansible/pull/74937 https://github.com/ansible-community/antsibull/pull/281 https://github.com/ansible-collections/community.dns/pull/23
15:46:03 <samccann> felixfontein sorry I'm not remembering the topic at all :-(
15:46:21 <felixfontein> samccann: or maybe it was someone else who said that they want to look it up :)
15:46:27 <felixfontein> I tried to search for that recently and couldn't find it
15:47:50 <felixfontein> hmm, I'm somehow remembering that dmsimard was involved in this (but maybe I'm also completely off)
15:48:17 <samccann> #info key=value pair rendering - IBM style guide suggests monospace
15:48:55 <samccann> that's about the closest I can find to a definition on how it should look
15:49:09 <felixfontein> we discussed this with several examples, and I think we also voted on something
15:49:12 <acozine> there are three parts to this, right? 1. defining the syntax (for example, `KV(key=value)` could be the syntax for presenting key/value pairs), 2. defining the output (for example, key/value pairs should appear in `monospace`), and then 3. updating the docs to use the new syntax
15:50:07 <felixfontein> it's `O(k=v)` actually :)
15:50:12 <acozine> heh
15:50:22 <felixfontein> according to https://github.com/ansible/ansible/pull/73137/files  ;)
15:50:29 <samccann> ah okay so looking at the example output, I recall the conversation a bit more now. It has italics for key and monospace for value, right?
15:51:03 <samccann> example here -https://ansible.fontein.de/collections/community/dns/hosttech_dns_records_module.html#parameter-records/value
15:51:10 <acozine> felixfontein: heh, that sounds great
15:51:14 <acozine> O for Option
15:51:54 <samccann> the joy of semantic markup is if we decide we don't like how it renders, we can change it! ;-)
15:52:35 <samccann> cyb-clock-clone sez we are 52 min into the meeting and 10 min into the current topic
15:52:52 <felixfontein> I found https://github.com/ansible/community/issues/521#issuecomment-739263018, and now I found https://meetbot.fedoraproject.org/ansible-docs/2020-12-15/dawgs_aka_docs_working_group.2020-12-15-16.01.log.html
15:54:01 <acozine> excellent sleuthing!
15:55:14 <samccann> #info - older discussions on this topic https://github.com/ansible/community/issues/521#issuecomment-739263018 and https://meetbot.fedoraproject.org/ansible-docs/2020-12-15/dawgs_aka_docs_working_group.2020-12-15-16.01.log.html (search for value)
15:55:19 <acozine> wow, it was a long discussion, I'm still hunting for the vote
15:55:23 <felixfontein> hmm, it looks to me like we didn't decide on something
15:55:26 <felixfontein> (or I overlooked it)
15:56:23 <samccann> I don't think we voted
15:56:41 <samccann> So maybe we put it up for a vote now quickly or punt to next week? We have 4 min left
15:57:01 <felixfontein> punt to next week might be better
15:58:01 <felixfontein> dmsimard's examples still work, it's probably a good idea to look at them again
15:58:23 <acozine> yeah, that makes sense
15:58:28 <samccann> okay I'll info all 5 of them for the meeting minutes
15:59:04 <acozine> samccann: awesome, I'm happy to create a GitHub issue that summarizes things, that may make it easier to vote next week
15:59:38 <acozine> okay, quick open floor, and bump semantic versioning to the top of the agenda for next week
15:59:44 <samccann> #action - review these rendering options to vote next week:
15:59:50 <samccann> #info 1. I(option=value) https://dmsimard.com/files/docsite/1/collections/ansible/builtin/lineinfile_module.html
15:59:53 <felixfontein> acozine: you mean semantic markup, not semantic versioning :)
16:00:03 <acozine> oh, lord, yes
16:00:08 <samccann> #info 2. C(option=value) https://dmsimard.com/files/docsite/2/collections/ansible/builtin/lineinfile_module.html
16:00:21 <samccann> #info 3. I(option)=C(value) https://dmsimard.com/files/docsite/3/collections/ansible/builtin/lineinfile_module.html
16:00:26 <acozine> bump semantic MARKUP to the top of the agenda for next week
16:00:30 <samccann> 4. I(option=)C(value) https://dmsimard.com/files/docsite/4/collections/ansible/builtin/lineinfile_module.html
16:00:38 <samccann> 5. B(option)=C(value) https://dmsimard.com/files/docsite/5/collections/ansible/builtin/lineinfile_module.html
16:00:50 <felixfontein> you're missing #info
16:00:53 <samccann> cyb-clock-clone sez we are at the 1 hr mark and she has to scoot
16:00:59 <acozine> I'll info them
16:01:06 <acozine> if you need to head out samccann
16:01:07 <samccann> oh dang haha
16:01:11 <samccann> thanks
16:01:21 <acozine> #info 4. I(option=)C(value) https://dmsimard.com/files/docsite/4/collections/ansible/builtin/lineinfile_module.html
16:01:21 <samccann> #unchair
16:01:21 <zodbot> Current chairs: Xaroth acozine bcoca briantist dericcrago felixfontein gundalow samccann
16:01:28 <acozine> #unchair samccann
16:01:28 <zodbot> Current chairs: Xaroth acozine bcoca briantist dericcrago felixfontein gundalow
16:01:38 <acozine> #info 5. B(option)=C(value) https://dmsimard.com/files/docsite/5/collections/ansible/builtin/lineinfile_module.html
16:01:42 <acozine> phew!
16:01:47 <acozine> #topic open floor
16:02:07 <acozine> all comments, questions, ideas, suggestions, criticisms welcome
16:02:24 <acozine> you don't have to be a chair of the meeting
16:02:32 <acozine> (though you can be)
16:02:48 <acozine> anybody have an open PR they'd like folks to look at?
16:02:58 <acozine> or an open issue that needs attention?
16:03:06 <acozine> preferably related to documentation, of course
16:03:44 <felixfontein> nothing from my side for now :)
16:03:50 <acozine> Everyone/anyone is welcome to add items to the agenda for next week (or any meeting), by adding a comment on https://github.com/ansible/community/issues/579
16:04:07 <acozine> all right then
16:04:12 <acozine> chat welcome in the channel at all times
16:04:37 <acozine> thanks Xaroth briantist dericcrago felixfontein gundalow lmodemal samccann
16:04:48 <acozine> see folks next week if not before!
16:04:50 <acozine> #endmeeting