15:00:57 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:58 <zodbot> Meeting started Tue Sep 27 15:00:57 2022 UTC.
15:00:58 <zodbot> This meeting is logged and archived in a public location.
15:00:58 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:58 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:58 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:13 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:13 <DonNaro[m]> o/
15:01:20 <samccann> #chair Don Naro
15:01:20 <zodbot> Current chairs: Don Naro samccann
15:01:32 <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:01:44 <DonNaro[m]> double booked as usual though but it's my last week!
15:01:44 <acozine> o/
15:01:54 <samccann> briantist: felixfontein around to talk docs today?
15:02:02 <samccann> #chair acozine
15:02:02 <zodbot> Current chairs: Don Naro acozine samccann
15:02:05 <samccann> and welcome
15:02:07 <briantist> o/
15:02:12 <briantist> (distracted)
15:02:28 * tremble is triple booked (as usual)
15:02:32 <samccann> #chair briantist tremble
15:02:32 <zodbot> Current chairs: Don Naro acozine briantist samccann tremble
15:02:40 <samccann> we take all the books!
15:02:41 <samccann> :-)
15:03:15 <samccann> official agenda at https://github.com/ansible/community/issues/643#issuecomment-1252599726
15:03:26 <samccann> #topic Action Item updates:
15:03:31 <samccann> #info resolved - Create tracking issue https://github.com/ansible-community/community-team/issues/60 to track all the collections that SHOULD consider using true/false boolean in examples  and also opened https://github.com/ansible-community/community-team/issues/61 to suggest adding changelogs to the collection rst fun.
15:03:57 <samccann> #info open - Consider an 'open docs hr' later in the week to regularly interact with docs contributors in a friendlier way than the expert details that happen in DaWGs meetings
15:04:05 <samccann> #info open add a link to a separate intro to the agenda for welcome/here's what you need to know/ etc so newcomers can prepare.
15:04:42 <samccann> Those last two are a result of us brainstorming last week on how to make space for newcomers etc. This meeting does tend to go VERY deep and may not be as new person friendly as we'd like.
15:05:33 <tremble> note re: #60/#61  I suspect most folks couldn't do the 'check' stage...
15:05:50 <anwesha> Hello everyone, I am a newcomer in here :)
15:05:58 <samccann> huzzah!!
15:05:58 <tremble> (check-off from the list stage)
15:06:05 <acozine> anwesha: welcome!
15:06:12 <anwesha> acozine, thank you :)
15:06:23 <samccann> #chair anwesha
15:06:23 <zodbot> Current chairs: Don Naro acozine anwesha briantist samccann tremble
15:06:32 <DonNaro[m]> hello anwesha welcome!
15:06:49 <samccann> So we chair everyone here. That gives you the ability to add to the meeting minutes with #info for example
15:07:17 <acozine> anwesha: what motivated you to join this channel or this meeting? Are you a writer? An Ansible user?
15:07:19 <anwesha> samccann, ahh understood, like in Fedora meetings.
15:07:31 <samccann> yes exactly anwesha
15:08:27 <samccann> tremble: so basically only I can check off the check boxes on those issues? (or someone else with rights to that repo)?
15:09:12 <tremble> samccann: Yup
15:09:20 <samccann> I suppose that makes sense but...
15:09:26 * samccann shakes fist at github
15:09:31 <tremble> I did try for community.aws :)
15:09:43 <samccann> lol thanks!
15:10:03 <anwesha> acozine, I am a lawyer turned to technologist. I am using Ansible for maintaining community and work infrastructure. So that is how I ended up in #ansible.I submitted a small docs PR ( https://github.com/ansible/ansible/pull/78884 ) yesterday, that is why thought of attending the docs meeting.
15:10:24 <acozine> I guess the rest of us can add comments to the issue saying "I added this issue to Repo X" with a link
15:10:26 <anwesha> DonNaro[m], thank you.
15:10:33 <samccann> So to give a bit of background - we have a lot of smaller issues we want to highlight to collection maintainers. So I opened those two issues above to 'track' them.
15:10:56 <acozine> Awesome anwesha - thanks for the PR, and for joining the DaWGs!
15:11:55 <samccann> True
15:12:04 <samccann> and thanks for the PR anwesha ! just merged it
15:12:26 <samccann> #topic Hacktoberfest
15:12:31 <anwesha> samccann, yeah, thank you.
15:12:41 <samccann> #info it's coming up in 1 week. What issues should we try to tackle with hactoberfest volunteers? Some ideas - https://hackmd.io/gNQ2TQW8T4ilcZc8JAM5fQ
15:13:29 <samccann> We have a batch of ideas there and we need to start opening issues and tagging them.  I think ariordan1 had a good strategy last year so I'll ask her help and advice.
15:13:43 <briantist> welcome anwesha !
15:14:01 <anwesha> briantist, hello :)
15:15:05 <samccann> for collection maintainers here - consider if you have some easyfix items in your repos you can tag as `hacktoberfest` as well. It's a great way to get the little things fixed for sure. Though it does come with a little PR spam on the first few days of the month
15:15:58 <samccann> #topic Documentation updates
15:16:05 <samccann> #info Ansible 7 alpha coming soon. When do we want to start staging docs on test?
15:16:44 <samccann> Last time, while I staged Ansible 6 on test, I didn't do it regularly, and didn't remind folks here to go look. Ended up we had problems :-)
15:16:58 <acozine> yeah, I'd say sooner is better than later
15:17:29 <acozine> especially with the changes we've made lately in the build pipeline
15:17:30 <samccann> yeah. It's an easy step for me - just start a jenkins job. So maybe I'll do that weekly from now til GA for Ansible 7
15:18:05 <samccann> again with a bit of background - our docs are static RST files for the guides, and autogenerated RST files pulled from collection module python files.
15:18:46 <samccann> We've definitely had a lot of work on `antsibull-doc`, the tool that does that autogeneration. As well as sidecar docs code that allows additional docs for filter and test plugins etc.
15:19:10 <samccann> #action samccann start weekly staging of core and Ansible docs to test and ping here for folks to review etc.
15:19:26 <samccann> #info archiving 2.3 docs archive hit a snag with redirects. No simple way to redirect all the modules to collections.
15:19:48 <samccann> This one is tricky. The goal was to archive al lthe older docs to an archive site so we can stop google from linking to them as top results
15:20:08 <samccann> we were going to redirect the older docs to /latest/, but I hit a block on this yesterday
15:20:32 <felixfontein> o/
15:20:37 <samccann> basically, all the modules would end up as 404s.  The only solution I can think of is running a script like Toshio did for the 2.9 to collections change ay back
15:20:46 <samccann> #chair felixfontein
15:20:46 <zodbot> Current chairs: Don Naro acozine anwesha briantist felixfontein samccann tremble
15:20:57 <samccann> welcome and just in time for redirect fun :-)
15:21:11 <felixfontein> sounds like fun indeed ;)
15:21:23 <samccann> So we have three options off the top of my head:
15:22:30 <samccann> 1 - give up on this as not worth the effort :-)
15:22:30 <samccann> 2 - live with 404s for anyone who bookmarked docs 2.8 and earlier for modules
15:22:30 <samccann> 3 - Rattle toshio's cage and find out how he did it the last time, if he remembers, and do it again, for 6 MORE releases.
15:23:02 <samccann> for #3  - that means adding 6K or more redirects, probably over 10K really (one for each module, for 6 releases)
15:23:15 <samccann> anyone have opinions?
15:23:56 <felixfontein> I'm tending a bit to 1... as the number of redirects is quickly getting out of hand...
15:24:44 <samccann> yeah it is a lot of redirects. But having 2.3 docs come up as 1, 2 or 3rd search result is also painful.
15:25:02 <samccann> I'll be honest, I'm tending to #2.
15:25:50 <samccann> I should add - we had ..erm.. I think I said yesterday 42K hits on the 2.3 docs for the month of September, out of a total of 3M overall?
15:26:37 <samccann> so like 2% of our traffic is what we're discussing here. If we go for option 2, we   would redirect 20K of those hits
15:27:23 <samccann> but of course, being honest, for a time -that would mean ADDING 404s to 20K hits a month (just for 2.3).
15:27:26 <felixfontein> can't we take the 2.9 → 2.10 redirects and adjust them a little so they work for 2.3 etc. as well?
15:27:44 <samccann> lemme dig them up
15:27:48 * samccann still hates that the docsite repo isn't publich
15:29:11 <samccann> RedirectMatch "^(/ansible/[^/]+)/plugins/become/doas.html" "$1/collections/community/general/doas_become.html"
15:29:11 <samccann> RedirectMatch "^(/ansible/[^/]+)/plugins/become/dzdo.html" "$1/collections/community/general/dzdo_become.html"
15:29:11 <samccann> RedirectMatch "^(/ansible/[^/]+)/plugins/become/enable.html" "$1/collections/ansible/netcommon/enable_become.html"
15:29:22 <samccann> well that didn't display nicely...
15:29:59 <samccann> but yeah, maybe if I just remove the /plugins/ part it would work. (2.3, 2.4 don't have that plugins subdir).
15:30:32 <samccann> Still brings up adding a lot more redirects, but maybe that's okay. Our search expert said it was 'no big deal' for modern servers
15:31:23 <samccann> erm.. it's 4k redirects, per release.
15:31:35 <samccann> tho older releases likely have less modules
15:32:16 <samccann> anyway, let me see if I can get them working, then we can debate whether it's a horrible idea :-)
15:33:14 <samccann> #action samccann to remove subdirs from toshio's batch of 2.9 <---> latest redirects to fix 2.3 redirect problems for EOL docs
15:34:19 <samccann> #info Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
15:34:19 <samccann> #info Help on issues always welcome :-)
15:34:36 <samccann> #topic doctools
15:34:57 <samccann> Anything we want to highlight here for hacktoberfest? any smaller issues (don't have to be docs, can be code etc) felixfontein ?
15:35:42 <felixfontein> I'll look at the redirects later, right now I'm only halfway here :)
15:36:16 <samccann> heh ok cool. also consider if you have any hacktoberfest issues you can tag in your repo(s). Same for everyone else!
15:36:19 <felixfontein> for hacktoberfest I'm not aware of anything that would be easy to implement, at least for antsibull-docs and related tools. maybe the GHA workflows/actions have something to do
15:36:21 <briantist> 🎵...livin' on a prayer
15:36:37 <samccann> heheh
15:36:45 <samccann> a little DaWGs background music!
15:37:04 <samccann> #info antsibull-docs fixes to consider - https://github.com/ansible-community/antsibull-docs/issues/38 and https://github.com/ansible-community/antsibull-docs/pull/43
15:37:27 <tremble> felixfontein: https://github.com/ansible-community/antsibull-docs/issues/35 might be nice, don't know how doable it is
15:39:14 <samccann> interesting. so I only update the intersphinx links at release time. It's not a particularly hard step to do so we could do it more frequently I suppose, but there's always going to be a lag between me remembering to do it, and when a collection actually moved modules around.
15:39:34 <felixfontein> tremble: there the hardest part (by a lot) is figuring out how to pass that information in. implementing it should be pretty easy once that hard part is done.
15:39:48 <samccann> for those following along - this section of the meeting is dedicated to the tooling in and around the docs.
15:41:00 <tremble> My specific use case is the community.aws and amazon.aws collections which have references between the two.  Only really an issue for the GitHub pages documentation.
15:41:25 <anwesha> samccann, thank you for the hints for the newcomer :)
15:42:08 <samccann> anwesha: np. It's something I should do for all meetings. We do have people who follow along but not say anything, so it likely helps many people
15:42:43 <tremble> felixfontein: My thought was possibly just a config file stored in the repo which could be appended to (or replace) the default template
15:43:31 <briantist> one option for the github-pages docs for the AWS collections is to publish a single docsite that includes the docs for both collections. So a single build.
15:43:57 <briantist> The tricky part is triggering it on changes to either collection, and pulling the right refs and stuff.
15:44:14 <tremble> briantist: Yeah, I did consider that and that's exactly what makes it tricky :)
15:45:20 <felixfontein> tremble: that would be a very simple way to do code injection into CI
15:46:41 <tremble> ergh, because of course it's executed
15:47:17 <briantist> which part would be code injection?
15:47:50 <felixfontein> 
15:47:54 <felixfontein> sorry
15:48:10 <felixfontein> briantist: if you can specify parts that are inserted into conf.py verbatim
15:48:13 <tremble> briantist: Allowing an arbitrary file from a collection PR to be injected into the sphinx configs
15:48:57 <felixfontein> though you can probably also find other ways to do that, depending on how ansible-core loads plugins
15:49:11 <felixfontein> (to extract docs)
15:50:59 <briantist> wouldn't the use of `pull_request_target` prevent that? or am I not following completely (I have been pulled away a lot this meeting)
15:52:47 <felixfontein> briantist: no, since the code comes from the repo checkout (which would be the PR's HEAD)
15:54:52 <briantist> which runs with limited permission though; same reason why code injection in a regular PR is not really impactful
15:55:33 <felixfontein> that's true
15:56:17 <felixfontein> though I still don't like the idea of blanketly including stuff into conf.py, same as I don't like blanket stuff like `extra_args` in CLI-tool-based modules ;)
15:56:43 <samccann> We're about 5 minutes to the end of the meeting.  let's do a quick open floor in case others have topics to bring up
15:56:43 <samccann> #topic Open Floor
15:56:51 <samccann> Here's the chance to bring up anything docs releated
15:56:54 <felixfontein> samccann: btw, we have a PR for the remaining filters in ansible-core: https://github.com/ansible/ansible/pull/78876#pullrequestreview-1122256197
15:57:05 <samccann> (and y'all can keep going on your CI code injection fun)
15:57:21 <acozine> Questions, ideas, suggestions are all encouraged during the open floor.
15:57:46 <samccann> felixfontein: cool I'll look in a bit
15:58:26 <samccann> felixfontein: I haven't heard back from Matt on merging an update to antsibull-docs, but bcoca did mention he has a couple more smaller PRs in the works so I think we wait til he's done, if matt's okay with that
16:00:28 <samccann> ok we are at the top of the hr... and things seem to have gotten quiet. Anything else before we end the meeting?
16:00:32 <felixfontein> thanks for the update!
16:00:36 <felixfontein> not from my side
16:00:59 <acozine> thanks everybody!
16:01:13 <acozine> thanks samccann for running the meeting
16:01:20 <samccann> #endmeeting