15:59:15 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:59:15 <zodbot> Meeting started Tue Mar  1 15:59:15 2022 UTC.
15:59:15 <zodbot> This meeting is logged and archived in a public location.
15:59:15 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:59:15 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:59:15 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:59:23 <samccann> #topic opening chatter
15:59:30 <samccann> @room Meeting time! Who is here to talk the docs?
15:59:39 <briantist> o/
15:59:42 <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:59:51 <samccann> #chair briantist
15:59:51 <zodbot> Current chairs: briantist samccann
15:59:53 <samccann> welcome!
16:00:22 <samccann> andersson007_: tadeboro around to talk docs today?
16:01:23 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1048091168
16:02:48 <samccann> ooo kay... might be a quiet day :-)
16:03:00 <samccann> #topic Documentation updates
16:03:09 <samccann> #info added accessibility guidelines to Ansible docs style guide.
16:03:25 <samccann> Just some simple things to keep in mind that help the docs be more readable etc
16:04:11 <acozine> sorry, I'm paired up and deep in an urgent change
16:04:19 <ariordan> o/
16:04:30 <samccann> ok no worries. I'll just assign all action items to you :-)
16:04:39 <samccann> #chair ariordan
16:04:39 <zodbot> Current chairs: ariordan briantist samccann
16:04:42 <samccann> welcome welcome!
16:05:18 <samccann> We need to discuss time changes since daylight savings starts up soon, but I don't think we have enough people for that today
16:06:02 <samccann> #info daylight savings time changes coming up soon. We need to decide if we shift this meeting so it stays the same after that or ...not.
16:06:28 <samccann> #info always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
16:06:54 <samccann> Help can come in the form of PRs or comments on either PRs or issues to help us understand the problems and/or verify the fixes etc
16:07:43 <samccann> we're still moving over community docs from that repo and making progress on that... bit by bit.
16:08:05 <briantist> don't we always come to the same conclusion on the DST thing? And isn't that conclusion that we keep the meeting the same (it shifts for people in DST, it doesn't for those who aren't)? Either way, should be decide this once and for all so it doesn't come up twice a year?
16:08:27 <samccann> That would be my preference, yes
16:08:29 <ariordan> +1
16:08:39 <samccann> but somehow we just got in the habit of asking each time and yeah, it's bothersome
16:09:12 <ariordan> Sometimes DST kicks in on different dates in different countries.
16:09:14 <samccann> We could try the alternate approach - to say we WILL adjust and scream if you disagree ;-)
16:09:19 <ariordan> We're changing on the 27th.
16:09:31 <samccann> US changes I think on the ..erm.. 13th?
16:10:14 <samccann> But last time we changed on Europe's change time so I think we stick to that and change on the 27th?
16:11:11 <ariordan> Sounds good to me, but I'm in Europe !
16:11:30 <briantist> I dunno.. to me it seems easiest to keep the meeting's same UTC time, and then the meeting changes naturally for each place when they apply DST. Using the calendar file helps to ensure that our calendars always show the right time.
16:11:58 <samccann> so that's the opposite of what we've been doing
16:12:07 <briantist> I'm in US, and I'm used to some/most of the Ansible meetings shifting by an hour twice a year...
16:12:53 <samccann> If we fix it to UTC then yes, it will shift twice a year. Then we had problems in the past where folks like felixfontein couldn't make it because it hit his train time I think?
16:12:58 <briantist> anyway I'll go with the flow of whatever, it doesn't make a huge difference to me either way, but it would be nice to make a single decision and apply it going forward until/unless we decide again to change it
16:13:57 <samccann> I'll ping some typical attenders later and see what they think.
16:14:08 <briantist> sgtm
16:14:21 <samccann> #topic doctools
16:14:32 <samccann> #info Jenkins docs builds are busted again. I updated them all to use centos8-stream - http://mirror.centos.org/centos/8-stream/
16:14:47 <samccann> I'm still having some problems but I'll troubleshoot them later today.
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:26 <samccann> my big question to 'anyone in the know' - do you think it is risky to use centos8 stream for production docs builds (the ones that get triggered by an ansible-core release)?
16:18:43 <samccann> #action samccann to ping individuals not here about DST time shift for the meeting
16:19:00 <samccann> #action samccann to ping 'someone in the know' about using centos8-stream for production docs
16:19:46 <samccann> gonna give another shout out to briantist and his docs validation PR work! I pulled it locally and used it to verify a collection doc before it was merged!
16:20:01 <samccann> it's not in ansible the package yet, but at least I have the wwarm fuzzy feeling that it should work
16:20:41 <briantist> thanks samccann ! and once again a huge shoutout to felixfontein since that is mostly his work under the hood!
16:21:00 <samccann> yay Felix Fontein !!
16:21:27 <briantist> btw I don't have any particular feelings on centos stream... but a lot of people do; this may be a helpful thread to read (or not I dunno haha): https://github.com/ansible-collections/news-for-maintainers/discussions/4
16:21:58 <samccann> oh cool, thanks! I'll give that a read
16:22:27 <samccann> #info community-topic to discuss if we want to have unversioned docs (like community/contributor guides) - https://github.com/ansible-community/community-topics/issues/68  Please add your comments there.
16:22:55 <samccann> ^^ that's an older one but still looking for feedback. What I've gotten so far is our strategy right now (publishing unversioned docs to devel only) is confusing people.
16:23:14 <samccann> So I may have to go back to backporting changes to /latest/
16:24:19 <samccann> Background on why we did this to begin with - was because we weren't backporting all the relevant PRs so things like porting guides were always out of date on /latest.
16:24:42 <samccann> I feel like that one was the biggie but then we extended it to the release/maint page as well.
16:25:12 <samccann> anyone know of a github trick to ping me when a PR is merged on a 'page of interest' like those? That would be helpful
16:27:36 <briantist> samccann: I don't know a way to do that other than creating a GitHub Actions workflow that triggers on PR merge of specific paths
16:28:03 <briantist> it's not terribly difficult but it probably feels a little heavy handed to some
16:28:26 <samccann> #action samccann to investigate creating a GitHub Actions workflow that triggers on PR merge of specific paths for keeping porting guide up todate in latest etc
16:28:53 <samccann> thanks, it's at least worth a look. Otherwise i'm haunting the repo once a week to see if something merged on my target pages or something
16:29:10 <samccann> I guess in general, I should be keeping a better eye on things to backport to latest but it takes time
16:29:18 <samccann> (and.. I confess...kinda boring)
16:29:52 <briantist> I can probably help with such a workflow, it would be pretty small, hardest part would be tweaking it to ensure the syntax and paths are correct, and then testing it
16:29:54 <samccann> but if I did it weekly, it's probably doable. We do that when a branch is pulled for an upcoming release.
16:30: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:30:46 <samccann> ok thanks briantist ! are workflows 'personal' so to speak? this would be in ansible/ansible so I don't want to step on core folks if it would be noticable to them
16:31:36 <briantist> they are not; so it would have to be accepted/merged into the repo, but the idea is that this would only trigger on the paths and events you specify
16:31:53 <samccann> ok worth a look see anyway, thanks!
16:31:57 <briantist> I figure the one thing it would do then, would be to post a simple comment on the PR after merge that @ mentions you
16:32:14 <samccann> yeah that would be helpful
16:32:18 <briantist> it would then technically be notifying everyone watching the issue.. but that's not so bad imo
16:32:44 <samccann> :-)
16:33:45 <samccann> #info adding extra links to collection and module docs pages - https://github.com/ansible-community/antsibull/pull/355
16:34:26 <samccann> ^^ that's getting closer to reality!  Felix has some good examples up
16:34:35 <samccann> #info an example of this in action - https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_module.html#collection-links
16:34:53 <samccann> So if you have an interest, please add your comments to the PR.
16:37:38 <samccann> ok onto another topic. Was hoping felix would be around for this one
16:37:43 <samccann> #topic semantic markup
16:38:27 <samccann> #info semantic markup will not be on the Red Hat product roadmap this year.
16:39:06 <samccann> #info community will need to consider a redesign for 'opt in' or delay this feature until it can be timed with the product roadmap down the road
16:39:39 <briantist> 😢
16:39:43 * samccann sadness abounds
16:39:53 <samccann> 😭
16:40:26 <samccann> yeah. unfortunately `ansible-doc --json` is..heh.. dare I say.. a 'controlled substance' :-)
16:41:30 <samccann> Ok time to open the floor
16:41:34 <samccann> #topic OpenFloor
16:41:58 <samccann> Here's the time to bring up whatever is on your mind.. Doc page causing you problems? PR you want some reviews on for docs?
16:42:58 <briantist> gundalow was nice enough to bring up the reusable workflow cross org issue with GH and someone has looked at it, but no movement so far: https://github.community/t/called-workflows-cannot-be-queued-onto-self-hosted-runners-across-organisations-enterprises-failed-to-queue-this-job-labels-ubuntu-latest/229355?u=briantist
16:43:31 <briantist> and thanks to those of you who added "me too" comments :)
16:43:36 <briantist> I got nothing else today though
16:43:36 <samccann> hopefully it'll get some attention
16:43:41 <samccann> :-)  no problem!
16:44:02 <samccann> ok we'll give it a couple of minutes in case anyone else has a thought or three before ending the meeting
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:30 * samccann still finds that funny ^^
16:45:55 <samccann> ok thinking that's about it today
16:46:00 <samccann> #endmeeting