16:02:04 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:02:04 <zodbot> Meeting started Tue Dec  7 16:02:04 2021 UTC.
16:02:04 <zodbot> This meeting is logged and archived in a public location.
16:02:04 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:02:04 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:02:04 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:02:05 <samccann> #topic opening chatter
16:02:25 * felixfontein goes downstairs
16:02:26 <felixfontein> brb
16:02:35 <samccann> #chair acozine felixfontein
16:02:35 <zodbot> Current chairs: acozine felixfontein samccann
16:02:51 <samccann> so who else is around to talk the docs?
16:03:05 <samccann> @room Meeting time!
16:03:27 <samccann> i don't think that actually works for me ^^
16:03:35 <felixfontein> re
16:03:44 <acozine> hm, I can't tell if it did anything or not
16:04:12 <samccann> If you have sound, it should have made a noise like acozine does
16:04:38 <felixfontein> hmm I see the marking in matrix, but I don't know if it made a special sound or something, and didn't look at the notification(s) in time
16:05:13 <samccann> meanwhile... andersson007_ deric.crago tadeboro dmsimard gundalow Gwmngilfen - you folks chatting docs today?
16:05:29 <gwmngilfen-work> samccann: it does work ;)
16:05:32 * gundalow waves
16:05:51 <gwmngilfen-work> i am only semi-here, no progress on my link thing, been busy with other fires
16:05:53 <samccann> #chair gundalow
16:05:53 <zodbot> Current chairs: acozine felixfontein gundalow samccann
16:06:09 <gundalow> samccann: You need to do `#chair gund<tab>`
16:06:18 <gundalow> oh, it did work
16:06:32 <samccann> Gwmngilfen: maybe I'm just hoping it does something it won't - get people to wave and join the meeting. Seems I still need to ping people individually?
16:06:54 <gwmngilfen-work> room pings work unless people have chosen to disable them. i saw it, i was just busy ;)
16:06:56 <samccann> gundalow: which 'nag' worked for you?  the @ room, or when I pinged you individually?
16:07:15 <gundalow> The `@room` pinged in Element for me
16:07:29 <gundalow> and the `@gundalow` also worked
16:07:35 <samccann> ok cool maybe it is working! much easier to do than dig out a list of nag names ;-)
16:07:48 <samccann> ok let's get started!
16:07:54 <samccann> #topic Action Item Review
16:08:20 <samccann> #info agenda - https://github.com/ansible/community/issues/579#issuecomment-983039814
16:09:54 <samccann> A number of things I didn't do yet (expand/collapse) and I have a vague note about Gwmngilfen  "review the proposed schema' I think that's the link thing he said he didn't get to yet
16:10:05 <gwmngilfen-work> thats the one
16:10:13 <gwmngilfen-work> and it was my action, you didnt miss anything
16:10:25 <samccann> I have a couple of things I DID get  to, but want  to cover those in separate topics. So I'll pause a bit and see if anyone else has action item updates
16:11:21 <acozine> I've still got that "when should a playbook become a role" thing on my plate
16:11:38 <samccann> #info action items still pending - expand/collapse, and better linking/metadata for collection pages, and 'when should a playbook become a role' doc ideas
16:11:39 <acozine> I created a branch for it, but I don't think I've done much with it
16:11:54 <samccann> :-) yep. I have a few of those hanging around as well
16:12:04 <samccann> ok  let's hop to a new topic
16:12:20 <samccann> #topic Responsive parameter tables
16:12:34 <samccann> #link https://github.com/ansible-community/antsibull/pull/335
16:12:43 <samccann> Which gets to one action item I did do...
16:13:21 <felixfontein> if there are no more comments / change requests on this one, I'd like to merge it and get it integrated into the devel docs soon
16:13:28 <samccann> #info devel docs also use 'known good' requirements. If we want to publish these responsive tables only to devel for a time, we will need to update the jenkins builds to do that (for just nightly builds to devel)
16:14:22 <felixfontein> or simply update the known good requirements in devel :)
16:14:26 <gundalow> +1 to merge 335
16:14:48 <samccann> felixfontein sounds good to me
16:15:00 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:15:02 <acozine> Felix Fontein: are the output links up to date with the branch?
16:15:35 <felixfontein> acozine: I think they are
16:16:06 <samccann> I can also 'hack' jenkins temporarily I think to publish to test for 335. I think I did that once before if we feel we should see this across the site before going 'live' on devel?
16:16:32 <samccann> (aka pull antsibull from that pr within jenkins)
16:16:42 * samccann wishes she kept notes on that but thinks she remembers
16:17:11 <acozine> not necessary, but with 20 commits I wondered if the illustrations had gotten stale
16:17:25 <acozine> just want to be sure I'm looking at the current thing
16:17:55 <samccann> ok I can do that later today then
16:18:09 <felixfontein> acozine: the images in briantist's post aren't accurate anymore, but the links are
16:18:24 <felixfontein> I just rebuild my docsite with that branch and uploaded it, rsync didn't copy anything :)
16:18:26 <samccann> #action samccann to publish https://github.com/ansible-community/antsibull/pull/335  to test before we merge
16:18:57 <samccann> ok anything else on this before we move on?
16:19:10 <acozine> +1 to merge
16:19:38 <samccann> as in merge before we put it on test? I mean it's devel, so I'm happy to just do that if the hive mind is okay with it?
16:19:42 <acozine> oof, when it passes CI
16:19:56 <acozine> oh, it's a codecov failure
16:20:04 <felixfontein> yeah, that one can be ignored :)
16:20:05 * acozine shakes fist at codecov
16:20:14 <gundalow> I think the two CI errors can be ignored (as they are just codecov warning about a drop of % coverage)
16:21:01 <samccann> so are we talking merge it now?
16:21:20 <felixfontein> there are still some steps between merge and the PR being used on devel
16:21:41 <felixfontein> like making a release, creating PR to update known working deps, and merging that one
16:22:11 <felixfontein> so even if we merge we can still build the test doc site with the new `main` branch of antsibull
16:22:17 <felixfontein> to see how it looks like
16:22:46 <felixfontein> I also want to get some other PR merged before releasing antsibull, so it will still be a few days before the devel updating PR can be created
16:22:49 <acozine> true, there's that buffer between antsibull and the active docs build
16:23:34 <acozine> I'd vote to merge now
16:23:56 <acozine> especially since devel is supposed to be less stable now anywya
16:23:58 <felixfontein> I'm abstaining from that vote, but I'm also tending to merge ;)
16:24:43 <samccann> #action felixfontein to merge 335 (responsive parameters) and move forward with next steps to an antsibull release
16:24:47 <samccann> there we go!
16:24:54 <samccann> ok next topic...
16:24:55 <felixfontein> \o/
16:25:00 <samccann> #topic semantic markup
16:25:07 <samccann> good news/bad news on this one
16:25:27 <felixfontein> we didn't manage to talk about it at the community meeting so far, last week we were busy with other things :)
16:25:39 <samccann> I finally did get some internal eyes on this, but mostly just enough to say this can't be in core-2.13, it has to wait til 2.14
16:25:51 <felixfontein> why can't this be in core-2.13?
16:26:32 <samccann> Because this feature impacts 'downstream' products, and the next downstream product roadmap so to speak is fixed in place, we have to wait to the 'next' one which will depend on 2.14
16:27:27 <samccann> the good news part (sort of) is that 2.13 branch gets pulled in theory I think in late march, and then we can move forward a bit
16:27:53 <felixfontein> so basically we see it in production in roughtly a year, earliest
16:28:03 <samccann> and in the meanwhile, I've been asked to create a formal 'spec' for this so we can get full buyin from those downstream products before that branch pull
16:28:18 <samccann> thinking out loud
16:28:32 <samccann> we see it on /latest/ a year from now sort of as a gues, yess
16:28:36 * samccann messes up her ss's
16:28:48 <felixfontein> yessss :)
16:29:01 <samccann> but I 'think say by late April, we could have this in devel and in community-only collections, right?
16:29:08 <samccann> heh
16:29:08 <felixfontein> when did we start this topic? wasn't it like a year ago? :)
16:29:23 <acozine> at least a year ago, yeah
16:29:29 <felixfontein> we cannot have this in community-only collections before the first stable branch of ansible-core supports it
16:29:38 <felixfontein> s/community-only //
16:29:44 <samccann> and I take the blame for this delay for sure. I should have pushed all of this a few months ago and we might have gotten approval for it in 2.13
16:30:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:30:04 <felixfontein> at least this way we have more time to figure out details of the spec
16:30:13 <samccann> ah.. you are right felixfontein  - wasn't thinking about that aspect
16:30:14 <acozine> I don't think this is an individual-blame scenario
16:30:22 <felixfontein> like https://github.com/ansible-community/community-topics/issues/53#issuecomment-972023499 and the comment after it
16:31:08 <acozine> anyway, how much work needs to be done on it?
16:31:46 <acozine> can we have PRs ready to merge the first day that `devel` is accepting changes for 2.14?
16:31:54 <samccann> felixfontein: yep, silver lining. I'll start the 'spec' in hackmd so we can review in community and make sure it's solidly what we want, and then ..erm.. copy that to 'someplace' internal RH people can start reviewing etc.
16:32:16 <acozine> ah, right, you said we need a formal spec for it
16:32:40 * acozine BRB, cat noises in the distance
16:32:40 <samccann> #info since semantic markup impacts products like Automation Hub, we cannot merge these until core-2.14 timeframe as all the roadmaps based on 2.13 have been finalized.
16:32:41 <felixfontein> samccann: sounds good!
16:33:01 <samccann> #info next step is a formal spec for this to be reviewed in community and then internally for these dependent products
16:33:15 <gundalow> Sounds good
16:33:33 <samccann> #action samccann felixfontein -work on semantic markup formal spec in hackmd
16:34:02 <felixfontein> :+1:
16:34:10 <samccann> ok gonna shift to another topic unless someone has more on this one?
16:34:12 <felixfontein> FYI: just merged https://github.com/ansible-community/antsibull/pull/335
16:34:24 * acozine is back
16:34:27 <samccann> \o/  progress!!!
16:34:34 <acozine> \o/
16:34:38 <gundalow> Thanks felixfontein
16:35:43 <samccann> #topic docs vs docs-tooling and attracting more contributors
16:35:58 <gundalow> ooooh
16:36:11 <samccann> This one came up recently. We took a bit of a look at the agenda and realized say 90% of it is docs-tooling
16:36:25 <samccann> which ya know, is where the real fun happens... ;-)
16:36:29 <felixfontein> :)
16:36:45 <samccann> But it made us think - anyone coming new to this meeting is instantly lost. Unless they want to help with doc-tools so to speak
16:37:17 <samccann> So I'm trying to think of a better way of handling things so we are welcoming to those who do want to help with words on paper so to speak
16:37:43 <samccann> But I'm also thinking, is this an opportunity to mimic some of the 'async' work the community team is  trying?
16:37:57 <acozine> do we still get good responses to issues marked `easy_fix`?
16:38:00 <samccann> aka can we async doc-tools? do we async 'docs-words-onpaper?"
16:38:21 <samccann> acozine: during hacktoberfest ariordan got quite a lot of PRs!
16:38:43 <acozine> maybe we could have a section of the DaWGs meeting where we give out kudos to new contributors?
16:39:08 <samccann> There are ways we can encourage that beyond that time, maybe a running note in the bullhorn - see 'easyfix' for ways to get involved (and also pick up coders for any core easyfix items labeled)
16:39:10 <acozine> speaking just for myself, the synchronous meeting time is a great reminder of the stuff I meant to do
16:39:47 <acozine> if we go full async I might go weeks without even thinking about contributions
16:39:51 <samccann> acozine: yeah I'm a little tied to the meeting as well, but we could then consider async on the docs-tooling
16:40:28 <samccann> or ariordan had the idea I think of maybe we split the agenda  and organize the first section on docs stuff for 20 min, and then the remainder on tooling
16:40:31 <acozine> how about a "this week's words" section of the agned?
16:40:39 <acozine> er, agenda
16:41:02 <acozine> heh, not a new idea, I guess
16:41:11 <samccann> lol great minds think alike
16:41:54 <samccann> felixfontein: since you are heavily involved in a lot of the docs-tooling stuff  with antsibull innovations - what do you think? Keep talking that stuff in the meeting, or try async?
16:42:12 <gundalow> I think adding a "Help wanted" section to Bullhorn would be cool.
16:43:02 <samccann> #action samccann cybette work on a 'Help wanted' section on the bullorn to add 'easyfix' issues or other ideas where people can hop in and help
16:43:05 <gwmngilfen-work> 💯
16:43:19 * samccann ponders the politeness of adding an action item to someone not here
16:43:22 <acozine> that's a great idea
16:43:30 <acozine> heh
16:43:31 <gwmngilfen-work> I'm also thinking we'll be promoting "discussion of the week" from the open community topics, or something like that
16:43:33 <felixfontein> samccann: some sync discussion is usually helpful :)
16:43:52 <felixfontein> besides that there's already a lot of async discussion going on, like for the responsive PR and for semantic markup
16:43:58 <gwmngilfen-work> example: https://matrix.org/blog/category/this-week-in-matrix#msc-status :)
16:44:20 <felixfontein> so at least spending a couple of minutes to sum up current progress during the meeting sounds like a good idea to me, so we don't simply forget about it :)
16:44:26 <samccann> ok thanks felixfontein  I think we'll try updating the agenda to have a clear 'talk about words' section first, and then move to doctools.
16:44:27 <gwmngilfen-work> (eagle eyes may notice the eerily similar "Final Comment Period" wording :P)
16:45:00 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:45:24 <felixfontein> samccann: it would be nice though to make the decision process more async, so that we don't restrict voting to folks who happen to show up in this meeting
16:45:38 <samccann> #info we should highlight a part of the agenda dedicated to documentation so newcomers know when we will talk docs vs docs tooling
16:46:19 <samccann> #action samccann to revamp the agenda to frontload some documentation issues/PRs/ideas before the tooling stuff...make nice headers ;-)
16:46:53 <acozine> Felix Fontein: true
16:47:09 <acozine> maybe we could have some kind of "Daily Something" in the channel
16:47:15 <acozine> like a PR for review or an issue to fix?
16:47:20 <samccann> felixfontein: true. I think the next 'big item' will be semantic markup which does have a proposal, and the more metadata for better linking on a collection. Does that have a propsal?
16:47:23 <acozine> to support async actions?
16:47:38 <samccann> acozine: yeah that's possible too, though I doubt I'd remember daily
16:47:49 <felixfontein> there's no 'proper' proposal for better linking yet
16:48:14 <felixfontein> I might start working on a PR for that, which then will have a proposal :)
16:48:24 <samccann> heh cool
16:48:42 <felixfontein> by having an extra file and not being part of galaxy.yml we can also get that into production soon, instead of having to wait another year ;)
16:49:12 <samccann> hah yep was just about to say that!
16:49:55 <samccann> But once we have the proposal, we internally can ping a few people to look at it/be aware.
16:50:04 <samccann> so it won't come as a surprise
16:50:20 <samccann> ok we have about 10 min left. probably time to open the floor
16:50:41 <felixfontein> yeah. parts of it can be also added to galaxy.yml if they like it, and eventually deprecated/removed from the extra file
16:50:44 <samccann> #topic Open Floor
16:51:03 <samccann> Here's the time to bring up whatever is on your mind related to Ansible docs!
16:51:52 <felixfontein> my cats want to bring up that the meeting should end soon so they will get fed :D
16:52:09 <samccann> HAHAHAHAHA
16:52:18 <gwmngilfen-work> felixfontein: is a "proper" proposal anything more than us agreeing on the metadata schema and then saying "can we do this?"
16:52:28 <gwmngilfen-work> or is there more process to it?
16:52:33 <felixfontein> one is sitting a few meters from me and staring at me, and the other can't decide on bugging me or sitting next to the other and staring at me :)
16:52:51 <samccann> Gwmngilfen: I got the feeling it was the same as your async communications stuff.
16:52:57 <gwmngilfen-work> (i guess am asking if there's more to it than adding a label to the exiting issue once we're happy)
16:52:57 <felixfontein> gwmngilfen-work: that's pretty much it
16:53:09 <felixfontein> gwmngilfen-work: or having a PR which implements it, and taking that as a spec ;)
16:53:13 <gwmngilfen-work> cool, just making sure I understand
16:53:50 <samccann> my nickel would be yeah, as long as either the issue description, or the first comment after that has the relevant details, that would be good. People won't want to scan 60 other comments to find out where the decision landed
16:53:52 <acozine> felixfontein: your cats must have sent a feline message to mine, they also want more kibbles
16:54:18 <felixfontein> hehe :)
16:54:31 <samccann> ok anything else to cover before the Great Cat Feeding Fest happens?
16:55:16 <samccann> #action Gwmngilfen to work on finalizing linking metadata for collections and turning it into a proposal
16:55:20 <acozine> I want to file an official request with the Matrix administrators for a cat emoji
16:55:32 <gwmngilfen-work> custm emoji is an open spec request
16:55:35 <samccann> lol
16:55:42 * gwmngilfen-work finds the MSC
16:55:56 <FelixFontein[m]> 🐱
16:55:58 <felixfontein> already there :)
16:56:17 <acozine> huh, why didn't it come up as a reaction option?
16:56:17 <felixfontein> if you type `:cat` you get some suggestions
16:56:22 <gwmngilfen-work> https://github.com/matrix-org/matrix-doc/pull/2545
16:56:23 <acozine> maybe I need lunch
16:56:43 <acozine> sorry samccann for derailing
16:56:56 <samccann> lol I'm gonna say yeah we are done
16:56:58 <samccann> #endmeeting