15:58:55 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:58:55 <zodbot> Meeting started Tue Mar  8 15:58:55 2022 UTC.
15:58:55 <zodbot> This meeting is logged and archived in a public location.
15:58:55 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:58:55 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:58:55 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:59:26 <samccann> hmm I think my laptop time does not match irc/matrix time cuz it looks by the timestamp like I'm two minutes early
15:59:32 * samccann plays hold music for a minute
16:00:03 <acozine> o/
16:00:13 <samccann> #topic opening chatter
16:00:21 <samccann> #chair acozine
16:00:21 <zodbot> Current chairs: acozine samccann
16:00:31 <samccann> @room Meeting time! Who is here to talk the docs?
16:00:38 <briantist> o/
16:00:41 <briantist> sorta here
16:00:41 <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:51 <samccann> #chair briantist
16:00:51 <zodbot> Current chairs: acozine briantist samccann
16:00:56 <samccann> we'll take sorta
16:01:20 <gwmngilfen-work> likewise, semi-here. expecting a call shortly but until then ... ;)
16:01:20 <thedoubl3j> o/ am around
16:01:24 <amott[m]> Here, but mobile (being driven) so only 75%
16:01:35 <ariordan> o/ I'm sort-of here also.
16:01:37 <samccann> #chair amott thedoubl3j Gwmngilfen ariordan
16:01:37 <zodbot> Current chairs: Gwmngilfen acozine amott ariordan briantist samccann thedoubl3j
16:01:40 <samccann> woot!
16:01:42 <acozine> hey thedoubl3j
16:01:47 <samccann> lot's of furniture today!!
16:02:00 <acozine> amott: we'll make all our posts really small so you can see them
16:02:08 <samccann> heh
16:02:09 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1055729319
16:02:16 <amott[m]> Lol
16:02:55 <samccann> ok let's hop to it then!
16:03:04 <samccann> #topic Documentation updates
16:03:29 <samccann> true confession time - I'm woefully behind on all my action items from this meeting
16:03:40 <acozine> heh
16:03:41 * gwmngilfen-work couldn't possibly relate
16:03:49 * acozine BRB with fresh tea
16:05:08 <samccann> #info Meeting time will say the current UTC until Europe goes to DST (March 27th) so for those in the US, this meeting will be one hour later for 2 weeks.
16:05:20 * samccann ponders if acozine has brewed enuf tea for the rest of us
16:05:27 <acozine> heh, I'm back
16:05:38 <acozine> my kettle probably isn't big enough for all the DaWGs
16:05:43 <samccann> heh
16:05:49 <gwmngilfen-work> that was far too fast for black tea...
16:06:02 <acozine> it's steeping here at my desk
16:06:07 <acozine> but not, it isn't black tea
16:06:33 <amott[m]> Might still be in the pot, brewing?
16:06:38 <acozine> s/not/no/
16:06:38 <briantist> depends, are you planning to sip the tea or spill it?
16:06:54 <acozine> knowing me, probably a combination of both
16:07:11 <samccann> hehe
16:07:21 <samccann> and why are there no ansible modules for brewing tea, eh?
16:07:36 * acozine checks calendar for Time-Change-Warp-Weeks
16:07:57 <samccann> meanwhile, I  need technical review on this docs pr https://github.com/ansible/ansible/pull/77216/files "Afer 2.10 collections can use vars plugins"
16:08:08 <samccann> as in, is it correct what it's changing?
16:08:34 <samccann> if anyone here is in the know, please put a comment on the PR so I can move it forward.. or... not.
16:09:18 <gwmngilfen-work> samccann: you could probably adapt [rfc 2324](https://tools.ietf.org/html/rfc2324) :P
16:09:30 <briantist> hm, I am not in the know, but I am very interested in the answers
16:09:50 <briantist> especially surprised if cache plugins in collections can't be used for inventory
16:09:55 <briantist> that would be pretty sad
16:10:33 <briantist> I have been planning both a vars plugin and a cache plugin for `community.hashi_vault` so, I will be following this PR
16:11:05 <samccann> ok glad it is of interest. I'll ping the core folks later to see if they can give it a technical review
16:11:23 <acozine> huh, that is interesting
16:11:54 <samccann> meanwhile, my standard plug...
16:11:56 <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:12:21 <samccann> even if you aren't up for fixing anything, comments, even thumbs up/me too help us prioritize work
16:13:11 <amott[m]> I'm looking into the ownership changing bug, but literally just started. I'll see if I can replicate and add a comment
16:13:53 <samccann> ok time for a topic change
16:13:58 <samccann> #topic semantic markup
16:14:27 <samccann> #info as a reminder, the proposal as currently designed is not a part of the Ansible/RH roadmap for this year
16:14:55 <samccann> The big question - can we redesign it as an opt-in approach? Do we keep it on hold for next year?
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:15 <samccann> I don't think felixfon1ein is around today?
16:15:30 <samccann> felixfontein: ? huh not sure which one works
16:15:37 <felixfontein> o/
16:15:48 <felixfontein> sorry was afk
16:15:49 <samccann> that one works LOL!!!
16:16:03 <samccann> #chair felixfontein
16:16:03 <zodbot> Current chairs: Gwmngilfen acozine amott ariordan briantist felixfontein samccann thedoubl3j
16:16:11 <samccann> no problem!
16:16:30 <felixfontein> what do you mean with 'optional'? that the collection declares (say in galaxy.yml or somewhere else?) that it supports semantic markup?
16:16:56 <samccann> well right now, it directly impacts `ansible-docs --json` and that's what's killing the idea for now.
16:16:58 <felixfontein> ansible-doc would have to know about that (and ansible-test as well), I'm not sure whether core would like something like that
16:17:18 <samccann> so if we could do 'something else' such that it doesn't impact the --json users?
16:17:32 <felixfontein> it will always impact the --json users
16:17:36 <felixfontein> there's no way around that
16:18:01 <felixfontein> --json basically dumps the documentation as-is from the plugins, and if the plugin documentation uses semantic markup, it's in the --json output
16:18:46 <felixfontein> which I guess basically means 'no we cannot'
16:19:04 <samccann> not unless --json strips it out, yeah. sigh.
16:20:22 <samccann> so I guess we are just on hold until it lands in a roadmap at some point
16:20:45 <samccann> #info --json basically dumps the documentation as-is from the plugins, and if the plugin documentation uses semantic markup, it's in the --json output
16:21:06 <samccann> #info So we are on hold with semantic markup until it lands in an official product roadmap
16:21:11 <gwmngilfen-work> 😢
16:21:44 <samccann> The internal bits and bobs (jira tix, official-looking PRD with official-looking words) are in place. So we've done what we can I think
16:22:09 <felixfontein> I guess we have to wait until the inflexible mountain starts moving then :)
16:22:25 <samccann> LOL yep
16:22:35 <samccann> 🕯️
16:23:17 <acozine> bummer
16:23:28 <samccann> #topic redirects
16:24:16 <samccann> #info to get Ansible collection redirects working 'way back in ansible 3' we had to remove the redirects that went from old docs.ansible.com/ansible/foo to docs.ansible.com/ansible/<version>/foo
16:24:49 <samccann> That ^^ has now come back to haunt us. Someone opened an issue about it the other day. Mind you this is the first issue in over a year since we made the change.
16:25:20 <acozine> do you have a link to hte issue?
16:25:38 <ariordan> https://github.com/ansible/ansible/issues/77204
16:25:38 <samccann> So my first question for the hive mind - how important is that old redirect? How often are people using the very very old (pre 2.3) urls for docs that had no version
16:25:41 <acozine> ariordan: thanks
16:26:28 <felixfontein> I guess you need to look in the webserver access logs to see how often they are needed
16:26:49 <samccann> ah good idea. I don't have access but someone here must
16:26:53 <acozine> those URLs became obsolete in Ansible 2.5
16:26:54 <gwmngilfen-work> wow, some hostility in that ticket. glad rebeccahh called it
16:27:20 <samccann> #action samccann to ask webserver folks for access logs to see how often these old urls are used
16:27:34 <samccann> I might be able to find out on some few select pages too, like the one in the issue.
16:27:59 <felixfontein> gwmngilfen-work: indeed!
16:28:29 <gwmngilfen-work> i guess the analytics might catch it, since the sidebar loads ...
16:29:16 <samccann> yeah that's my thought Gwmngilfen - since they aren't redirecting anymore, I can search and at least compare what's happening on our top pages to get a feel for it. It won't be 100% accurate, but it's a data point. If there are a thousand hits a month on one of those old pages, we'll know
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:15 <gwmngilfen-work> sometimes you only need one data point :). worth checking
16:30:24 <samccann> it still leaves us with the original problem though and why we removed it. I can't recall all the details, but I know we had to remove it to get collections working. So if we figure out that it's a painful enough situation, we'll need someone who understands redirects to help us dig through and maybe find an alternate
16:30:38 <acozine> hmmm
16:30:47 <samccann> #action samccann to check web analytics for these older unversioned urls
16:30:50 <acozine> that URL is actually even older than I thought
16:30:57 <acozine> there's no version in it at all
16:31:12 <acozine> this one works: https://docs.ansible.com/ansible/2.3/playbooks.html
16:31:12 <samccann> yeah that's why I figure it predates 2.3
16:31:35 <samccann> and 2.2/2.1 I think exist on readthedocs somewhere, owned by someone else etc
16:32:00 <acozine> and if you hit `/latest/playbooks.html` it correctly redirects to the current page, which is in `/user_guide/`
16:32:16 <samccann> yep.
16:33:08 <acozine> if we really removed any redirects, the traces will be in the `docsite` repo
16:33:08 <thedoubl3j> apologies for the lack of contributions, attempted to change networks at the office and things went down hill from there
16:33:23 <samccann> acozine: yes we really did
16:33:58 <acozine> I believe you, I just don't remember it
16:34:00 <samccann> #info redirect removed by https://github.com/ansible/docsite/pull/38
16:34:30 <acozine> most folks will get a 404 for that link
16:34:50 <samccann> sigh. yeah, I need to  see if we can open up that repo.
16:34:54 <samccann> lemme pastebin it
16:35:23 <acozine> thedoubl3j: where's the `:skiing:` emoji when you need one?
16:36:01 <gwmngilfen-work> custom emojis are coming :P
16:36:22 <samccann> #info the relevant diffs - https://pastebin.com/kMvgKFLJ
16:36:57 <thedoubl3j> haha for real, but make it so there are no poles because that is what it felt like, got dropped off a call, all open IRC sessions etc and then I couldn't join back the original network I was on. eventually found a cat6 and just plugged into the wall
16:37:20 <samccann> ok probably enough on this one for now. Just want folks thinking about redirects and if they know how they work etc. Because we lost our  two relative experts so I'm ..lost
16:37:26 <samccann> moving on
16:37:32 <samccann> #topic doctools
16:37:43 <samccann> Thanks to acozine, I have lead on how to improve the 404 behavior (currently the left-hand navigation goes to latest no matter what version you started with).
16:38:00 <samccann> small potatoes, but it's another one of those things that annoys readers
16:38:21 <samccann> #info looking for help on https://github.com/ansible/ansible/issues/77054. Likely requires coding but not even sure where
16:39:04 <samccann> I'm sure the code is in ansible/ansible somewheres, but I doubt I have the coding chops to do much about it, even if I could find it. So it's open to anyone with an interest to poke at it
16:39:55 <thedoubl3j> attempting to find it now just to see where it is looking
16:40:00 <samccann> felixfontein: Gwmngilfen - any updates or next steps for the additional links to collectin/module pages PR?
16:40:17 <samccann> cool thanks thedoubl3j if you find it, post it in a comment so we at least know where to look
16:40:42 <gwmngilfen-work> i haven't had chance to revisit it, but I've at least followed the discussion so far. I think the debate is progressing in a good direction, just need to go add some +1s
16:41:42 <gwmngilfen-work> i've bumped the urgency in my todo list ;)
16:41:53 <samccann> #info take a look at https://github.com/ansible-community/antsibull/pull/355 and post comments or +1s etc
16:43:34 <samccann> Ok we have a few minutes left so let's open the floor
16:43:38 <samccann> #topic Open Floor
16:43:51 <samccann> Now's the time to bring up anything docs-related on your mind.
16:44:19 <samccann> favorite or stalled issues/prs? General comments? sparkly new ideas? all welcome
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:46:34 <acozine> I put a comment on #77216 - indeed, vars plugins are supported in collections since 2.10
16:46:43 <samccann> great thanks!!
16:46:54 <acozine> I included a link to the PR that introduced the feature
16:47:04 <samccann> perfect!
16:47:36 <acozine> so briantist you can rest easy about adding vars plugins to your collection(s)
16:47:42 <samccann> :-)
16:48:01 <felixfontein> there are almost no vars plugins in collections, the only case I know about is community.sops :)
16:48:23 <felixfontein> (https://docs.ansible.com/ansible/devel/collections/index_vars.html)
16:49:06 <acozine> heh, well, just because it's possible, doesn't mean folks actually do it
16:49:18 <felixfontein> about extra links: I guess comments would be useful. there are some things that are worth discussions I think, but if it's only Greg and me writing on them (and not having the same opinion) it won't really resolve :)
16:50:40 <samccann> ok sounds like this PR is correct - https://github.com/ansible/ansible/pull/77216
16:50:40 <samccann> tho I need to change the links for sure
16:51:17 <samccann> felixfontein: any points you want us to discuss here now since we have a few people around?
16:51:44 <felixfontein> it should be 'ansible-base 2.10' and not 'Ansible 2.10' though in 77216 ;-)
16:51:55 <acozine> felixfontein: I have opened a tab for the extra links PR . . . will try to read through it this week
16:52:05 <acozine> and comment
16:52:33 <felixfontein> 1) should communication links be simply added as extra buttons, or kept as a separate section (and one button link to it)
16:53:24 <felixfontein> 2) should buttons be centered, or aligned differently?
16:53:56 <felixfontein> also there is https://github.com/ansible-community/antsibull/pull/355#issuecomment-1057397438 with some concrete questions
16:55:30 <samccann> 2 - I prefer left-aligned on the buttons.
16:55:47 <felixfontein> samccann: did you try it out?
16:55:51 <acozine> 1 - I'd add everything as extra buttons, fewer clicks == more action
16:55:59 <samccann> 1 - I prefer communications links as links, not buttons. I don't want too many buttons
16:56:26 <acozine> oh, I wasn't thinking links vs. buttons, but more one thing vs. multiple things
16:56:27 <samccann> felixfontein: try it out? I looked at the most recent example I think https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_module.html#collection-links
16:56:27 <gwmngilfen-work> i'm with acozine, more pageloads / clicking will drop users
16:56:46 <gwmngilfen-work> but i need to go put that on the PR :)
16:56:54 <acozine> heh, yep, me too
16:57:20 <felixfontein> I prefer longer text for communication channels (to be able to tell which one to use for what), which makes them not really suitable as buttons
16:57:31 <samccann> if we have big teal buttons for everything, I feel it gets harder to find what you want, not easier
16:57:39 <felixfontein> samccann: I mean, did you modify CSS in inspector to have them left-aligned?
16:58:06 <samccann> I also feel (lots of feels lol) that most people will be clicking a button to go to the issues, open a PR etc. Less people will be going to the communications channels. But that's just... a ..feeling
16:58:19 <acozine> ah, interesting - I'll go look at what the buttons are for and what they say
16:58:26 <samccann> felixfontein: lol I'm not that clever but I'll try it after the meeting now that you mention it!
16:58:39 <felixfontein> also you will have at least two buttons per collection for communication, and potentially more
16:59:15 <felixfontein> like #ansible via matrix and IRC for users (two buttons), #ansible-community via matrix and IRC for folks interested in development (two more buttons) - makes four buttons already just for communication
16:59:26 <acozine> ah, I see what you mean
16:59:31 <gwmngilfen-work> i still don't understand why you (in general) want more than one
16:59:35 <felixfontein> samccann: I put the CSS you need into https://github.com/ansible-community/antsibull/pull/355#issuecomment-1057397438 ;)
16:59:55 <gwmngilfen-work> (per platform, ofc)
16:59:55 <felixfontein> gwmngilfen-work: mostly because there are different audiences, and not everyone is in every channel
17:00:00 <acozine> sorry, folks, I have a hard stop at the top of the hour
17:00:04 * acozine waves
17:00:14 <felixfontein> I'm for example not in #ansible, but usage questions should be asked there and not in #ansible-community
17:00:22 <felixfontein> bye acozine!
17:00:41 <gwmngilfen-work> we can't expect the reader to get that right, they won't (they don;t today either)
17:00:53 <felixfontein> so for a collection of mine I would mention both #ansible and #ansible-community, for example
17:01:05 <gwmngilfen-work> better for the collection owner to direct chat to the room they are in, aand redirect the user on from there
17:01:42 <felixfontein> there still will be three buttons (mailing list, irc, matrix) just for communication
17:01:52 <samccann> my nickel - we make some decisions this week and merge this
17:02:24 <samccann> once it's visible, we can play with style, more buttons, etc. I don't think any of the visual stuff impacts what collections owners need to do to start using this new feature
17:02:34 <gwmngilfen-work> are the mailing lists really taht used for colelction questions? (I don't subscribe, so I don't know)
17:02:42 <samccann> the sooner we have it out there, the sooner collections can start using it and have it all ready for Ansible 6
17:02:42 <gwmngilfen-work> wow my typing is off today ...
17:02:44 <felixfontein> gwmngilfen-work: they are
17:02:51 <felixfontein> at least ansible-project is
17:02:56 <gwmngilfen-work> fair enough
17:03:11 <ariordan> I'd prefer links instead of the communication button; the rest of the buttons link to GitHub, so it might be handy to see the destinations for Communications
17:03:20 <ariordan> But it's just a personal preference
17:03:40 <gwmngilfen-work> i'm biased the other way because chat is my thing I guess :)
17:03:45 <samccann> hehe
17:04:03 <gwmngilfen-work> samccann: that seems sensible. lets get it into people's hands and ask what they want from it
17:04:12 <samccann> cool
17:04:14 <felixfontein> ariordan: do you mean the communication link should be a link and not a button (i.e. we have buttons and links next to each other)?
17:04:24 <felixfontein> (also you can see the destination by hovering over it, the buttons are in fact just links)
17:04:38 <samccann> I'll play with the ccs felixfontein later today, but my nickel is if you think the PR is ready, merge
17:04:45 <samccann> we can play later with style things
17:04:57 <samccann> CSS ..yeesh
17:05:08 <felixfontein> we might want to talk about which links/buttons should be in the ansible.builtin collection
17:05:30 <felixfontein> (these are generated by the code, and I don't want to flood core pages with stuff I invented without some feedback ;) )
17:05:32 <samccann> felixfontein: does your PR make those changes (to ansible.builtin?
17:05:59 <felixfontein> https://github.com/ansible-community/antsibull/pull/355/files#diff-81dcd7b3ffe8fe9d6bc5962ad8c9dc1f2053087277f96d24eeffa14549d3f18dR35-R62 <-- that's the stuff for ansible.builtin
17:06:24 <felixfontein> samccann: it simply has some hard-coded links / data shown for ansible.builtin
17:06:48 <samccann> #action all - review the ansible.builtin links/buttons here - https://github.com/ansible-community/antsibull/pull/355/files#diff-81dcd7b3ffe8fe9d6bc5962ad8c9dc1f2053087277f96d24eeffa14549d3f18dR35-R62
17:06:53 <felixfontein> https://ansible.fontein.de/collections/ansible/builtin/
17:07:14 <samccann> #info builtin links/buttons - https://ansible.fontein.de/collections/ansible/builtin/
17:07:14 <felixfontein> that's how it looks like on the index page, and https://ansible.fontein.de/collections/ansible/builtin/apt_module.html#collection-links on a module/plugin page
17:09:05 <ariordan> felixfontein: Yes, that was my suggestion. It's only a personal preference, though. The buttons look good.
17:09:11 <samccann> cool. I'll put those out to the core folks for feedback as well. Is there anything else holding back a merge of this feature?
17:09:23 <gwmngilfen-work> have to dash. thanks folks!
17:10:25 <samccann> thanks Gwmngilfen
17:11:41 <samccann> ok perhaps we are winding down here in the meeting. Anything else before I end it?
17:12:54 <samccann> ok thanks everyone!
17:12:59 <samccann> #endmeeting