15:59:19 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:59:19 <zodbot> Meeting started Tue Feb  8 15:59:19 2022 UTC.
15:59:19 <zodbot> This meeting is logged and archived in a public location.
15:59:19 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:59:19 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:59:19 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:59:26 <samccann> #topic Opening chatter
15:59:36 <samccann> @room Meeting time! Who is here to talk the docs?
15:59:56 <gwmngilfen-work> i'm here
15:59:57 <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!
16:00:05 <samccann> #chair Gwmngilfen
16:00:05 <zodbot> Current chairs: Gwmngilfen samccann
16:00:11 <gwmngilfen-work> not that i have much to say, since I havent done anything on those links, sigh
16:00:29 <samccann> :-)
16:00:42 <samccann> sometimes it's just nice to stop by and say hello ;-)
16:02:03 <samccann> andersson007_: tadeboro felixfontein briantist cyberpear - y'all up for talking the docs today?
16:02:22 <felixfontein> hi :)
16:02:29 <briantist> o/
16:02:38 <samccann> #chair felixfontein briantist
16:02:38 <zodbot> Current chairs: Gwmngilfen briantist felixfontein samccann
16:02:39 <felixfontein> I will not really be around today, but I try to listen in from time to time and give comments :)
16:02:41 <samccann> welcome welcome
16:02:44 <briantist> same
16:02:51 <samccann> heh ok no worries
16:03:42 <samccann> #topic Documentation Updates
16:03:46 <acozine> hullo!
16:03:54 <samccann> #chair acozine
16:03:54 <zodbot> Current chairs: Gwmngilfen acozine briantist felixfontein samccann
16:04:08 <samccann> #info - colleciton maintainers guide PR - https://docs.ansible.com/ansible/devel/index.html and staged at http://docs.testing.ansible.com/ansible/devel/community/maintainers.html
16:04:59 <samccann> This is mostly just moving files over from the community-docs repo so we can publish them. It includes some light editing, but I'm hoping to move everything over, then do a deeper edit/minimalism brush over it all
16:05:00 <samccann> comments/feedback most welcome
16:05:34 <acozine> That looks good, it fits well under Contributing to Ansible
16:06:10 <samccann> yep and is set up to only publish for the ansible docs, not ansible-core docs
16:07:13 <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:07:39 <samccann> Comments, reviews, even testing out what the docs PR is saying to make sure it's valid... all helps move things along
16:08:25 <samccann> #info we have the start of a repo of community-curated examples - https://github.com/ansible-community/community-examples
16:08:41 <samccann> So we are still looking for community examples to fill in the new repo!
16:09:28 <samccann> Anyone else have updates on documentation before we move on to docTools etc?
16:10:08 <acozine> I'm looking at hte examples repo
16:10:54 <acozine> and these are not easy to see
16:11:01 <acozine> https://github.com/ansible-community/community-examples/tree/main/examples/core
16:12:07 <acozine> Is the GitHub repo the primary way to view the examples?
16:12:25 <samccann> I don't think we figured that out yet
16:12:37 <acozine> ah, gotcha
16:12:43 <samccann> The idea was to have a bunch of examples that also passed CI (so we know they are valid)
16:12:49 <acozine> that makes sense
16:13:11 <samccann> We never quite figured out how we would get users to see these examples once we had them.
16:13:15 <acozine> but users are used to the examples in the module docs, which are easy to read
16:13:19 <acozine> hm, yeah
16:14:00 <samccann> This is the todo issue - https://github.com/ansible-community/community-examples/issues/2
16:14:07 <acozine> if they're all going to be structured the same way, with an example and a related test, then maybe a page that explains that, with (dare I suggest it) an example?
16:14:17 <samccann> Maybe add thoughts there in a comment about how do we make them readable/understandable to a general user?
16:14:27 <acozine> ah, excellent, will do
16:14:53 <samccann> cool thanks!
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:09 <samccann> Any other thoughts on documentation itself before we go to tooling?
16:15:43 <samccann> For any newer folks, please do pipe in at any time with your thoughts or questions. Happy to explain anything that's confusing.
16:15:57 <samccann> We do tend to chatter back and forth without giving background explanations sometimes.
16:15:59 <acozine> now that I'm back to using Ansible to manage servers day to day, I'm deeply grateful for the module documentation
16:16:06 <samccann> :-)
16:16:33 <samccann> Are you all in on collections now?
16:16:34 <acozine> it's so great to have a predictable, consistent format
16:16:54 <acozine> heh, well, collections is how Ansible works now, so that's how we work too
16:17:16 <samccann> cool cool. user feeback always welcome :-)
16:18:18 <samccann> ok let's swing to the next topic
16:18:26 <samccann> #topic doc tooling updates
16:18:42 <samccann> #info favicon fix in the works - https://github.com/ansible-community/sphinx_ansible_theme/pull/49
16:19:13 <samccann> Thanks to felixfontein gundalow and others, who noticed the little icon at the top of a browser tab wasn't working for some browsers.
16:19:38 <samccann> If you've got some coding chops, please do pop into the PR with review comments etc
16:20:15 <samccann> https://matrix.to/#/!ZiHKxiCHRtflvQEbRt:libera.chat/$nYmfLdxL04UQwN37W4W03b9QCKFQTSiJs1P1vjNKgbQ?via=ansible.com&via=libera.chat&via=matrix.org
16:20:15 <bcoca> didnt major browsers stop using favico ?
16:20:36 <samccann> well that didn't work. Sorry for the noise, was trying to 'share' a messages from another channel here
16:20:56 <samccann> bcoca: they still work but I guess there were some problems with our older approach to it.
16:21:08 <samccann> Next steps would be... (full message at https://libera.ems.host/_matrix/media/r0/download/libera.chat/7d7bdaf08e1962c252431bb2385f1202a542b514)
16:21:41 <samccann> ooo the option to post a message from one room to another is Forward, not share!  TIL
16:22:43 <samccann> THEN we have to decide, can this be backported to stable-2.12 so it shows up on latest. That's a bigger question because there's been a lot of work happening in this area (sphinx theme and antsibull) and in my mind, all of that was staying in devel to 'stew' so to speak. Specifically thinking the module docs table changes and some other ideas. It's possible we could get away with just backporting the updated theme but I don't know off
16:22:44 <samccann> the top of my head.
16:23:06 <acozine> when is 2.13 schedule to release?
16:23:22 <acozine> as in, how long would most users have to wait for all these theme updates?
16:23:59 <samccann> 2.13 release is end of May
16:24:35 <samccann> But with just me as the writer, I don't really have the bandwidth to manage backports unless they are really important, and I don't feel a missing favicon falls in that category
16:24:37 <samccann> :-)
16:24:48 <acozine> yeah, that makes sense
16:25:20 <samccann> mostly, like I said, because there has been a LOT of work going on of late to improve/change the module docs and some of that tied into a  theme update as well. So..dunno if the theme patch on its own could go do latest or not
16:25:21 <felixfontein> bcoca: I think for Safari you actually have to enable it (at least I read that somewhere). but if users have it enabled, the site should better provide one the browser accepts :)
16:25:40 <acozine> I'd put favicons in the "nice to have" bucket
16:26:35 <felixfontein> they definitely are. but if there's a little work we can do to get them working for users who activated them in their browser, it's usually worth doing it. might be especially relevant for bookmarks.
16:26:43 * bcoca used to hide secret messages in favicons
16:27:19 <samccann> heh well ignoring bcoca's nefarious ways, I'm glad for the favicon fix, no doubts!  I'm just not sure it's worth backporting so it shows up on latest before 2.13
16:27:47 <samccann> just given what else might have changed in the  theme. Maybe I'm being too cautious and the PR would backport smoothly?
16:27:59 <samccann> I don't want to backport antsibull version for sure
16:28:07 <acozine> bcoca: do you need to read the favicons backwards to get the secret messages?
16:28:51 <acozine> samccann: you could try opening a backport PR and publish the branch to testing
16:29:40 <samccann> it time permits, yeah
16:29:51 <samccann> s/it/if/
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:04 * samccann curious if spelling edits here in matrix also show up on irc
16:30:34 <bcoca> acozine:  mostly was 'apparently random' darker pixels that made up a short ascii word
16:30:44 <samccann> ok do we have anything else stewing on the pot for docs tooling?
16:30:44 <bcoca> normally name of company
16:31:50 <briantist> added some improvements to docs build
16:32:00 <samccann> cool!
16:32:36 <briantist> mostly adding options to use existing antsibull flags, lenient and the new one for erroring out on module errors forgot the name already
16:32:45 <briantist> and an option for choosing a specific version of antsibull
16:32:46 <gwmngilfen-work> > * <@samccann:ansible.im> curious if spelling edits here in matrix also show up on irc
16:32:46 <gwmngilfen-work> it generally reposts the whole line with the chnage. so typos sure, but don't re-edit the same line 20 times unless you want trouble ;)
16:33:01 <samccann> heh thanks Gwmngilfen
16:33:09 <felixfontein> about https://github.com/ansible-community/antsibull/pull/397: should we keep the current formulation (and let someone else tackle the hard question on whether this should be changed somewhere else)?
16:33:49 <bcoca> samccann: edits wont show in irc
16:34:17 <samccann> felixfontein: I'm happy with the existing language
16:34:21 <bcoca> but we see the s/it/if/
16:34:39 <briantist> docs tools actions has some tests too, that's been helpful. still plenty of work to do there, needs documentation for users, more tests, and I support for github pages publishing, I've just been slammed with both open source and dayjob work lately so stuff is getting done more slowly than usual
16:34:59 <gwmngilfen-work> oh i forget they upgraded that feature to figure out the change and post an s/ instead
16:35:14 <samccann> thanks briantist for all the work you've put into that already!
16:35:58 <briantist> I wish I could dedicate like 2 weeks straight to it, I'm excited to get more folks using it
16:36:23 <samccann> :-) will be great for sure!
16:36:30 <briantist> big thanks to felixfontein for his contributions and reviews as well (to say nothing of the work on antsibull that makes it all possible)
16:36:42 <samccann> do we have any other tooling topics for today?
16:37:43 <samccann> I can say I'm in the process of turning the semantic markup spec into an official corporate-like PRD to move it forward internally here. (aka hasn't fallen off the radar yet)
16:38:12 <acozine> the wheels of corporate change grind "slowly but fine"?
16:38:27 <briantist> nice, big fan of semantic markup will be great to have
16:38:33 <samccann> here's hoping!  Haven't done this at this corp before so.. exciting times ahead!
16:39:29 <samccann> ok time for...
16:39:33 <samccann> #topic Open Floor
16:39:34 <felixfontein> gwmngilfen-work: what's the current state of the links proposal?
16:39:42 <samccann> Here's the time to bring up anything else!
16:39:52 <gwmngilfen-work> felixfontein: i haven't had time to move on it. firefighting :/
16:40:00 <gwmngilfen-work> hopefully this week!
16:40:05 <felixfontein> ok :)
16:40:13 <felixfontein> it would be great to get this into 2.13
16:41:07 <felixfontein> (the only core change required is to bump antsibull, but that gets harder to backport once 2.13 RCs start)
16:41:57 <acozine> four months to go, so the clock is ticking, though it's not very loud yet
16:42:01 <samccann> The branch pull happens on 3.28 according to the roadmap
16:42:08 <acozine> oh
16:42:09 <samccann> 3/28 that is
16:42:12 <gwmngilfen-work> felixfontein: whats the deadline for that?
16:42:16 * acozine hears the clock ticking much more loudly now
16:42:27 <gwmngilfen-work> oh, 28th March? ok, I will prioritise
16:43:35 <samccann> #info 2.13 branch pull scheduled for 3/28 so changes for antsibull and other tooling that needs core changes should happen before then
16:44:50 <samccann> Any other items to discuss before we close out 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:47:05 <samccann> ok guess that's a wrap folks!
16:47:11 <gwmngilfen-work> 👏
16:47:14 <samccann> #endmeeting