16:04:10 <gundalow> #startmeeting Documentation Working Group aka DaWGs
16:04:10 <zodbot> Meeting started Tue Feb  1 16:04:10 2022 UTC.
16:04:10 <zodbot> This meeting is logged and archived in a public location.
16:04:10 <zodbot> The chair is gundalow. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:04:10 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:04:10 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:04:20 <briantist> o/
16:04:34 <gundalow> #chair acozine felixfontein briantist lmodemal
16:04:34 <zodbot> Current chairs: acozine briantist felixfontein gundalow lmodemal
16:04:44 <acozine> o/
16:04:45 <gundalow> #topic opening chatter
16:04:54 <gundalow> @room ready to talk the docs?
16:05:47 <acozine> let's do it
16:06:38 <gundalow> #info Agenda https://github.com/ansible/community/issues/643#issuecomment-1021482151
16:07:07 <gundalow> I don't have any info, apart from the above
16:07:15 <gundalow> Which topics would you folks like to talk about
16:07:32 <acozine> heh, you need to run with the DaWGs more often!
16:07:35 <gundalow> #topic Documentation updates
16:07:35 <gundalow> 16:02:13 <samccann> #info - start of splitting co
16:07:43 <gundalow> * #topic Documentation updates
16:08:12 <acozine> I'm currently double-meetinged
16:08:26 <acozine> working on our Molecule setup
16:08:50 <lmodemal[m]> #unchair Sorry, I have a meeting that conflicts with this one :(
16:08:59 <gundalow> #unchair lmodemal
16:09:00 <zodbot> Current chairs: acozine briantist felixfontein gundalow
16:09:13 <lmodemal[m]> Have a nice day, everyone :)
16:09:21 <acozine> bye lmodemal
16:09:31 <gwmngilfen-work> sounds like a quiet week ;)
16:09:43 <gundalow> #info We've been looking at canonical url support to the Ansible 2.3 and 2.4 docs sites (as Google links to the old docs sometimes). To do this we'd need to backport the sphinx theme, which we've not looked into yet
16:10:44 <gundalow> felixfontein: I'm sure we can rebuild testing site. Is that from certain PRs?
16:11:30 <acozine> gundalow: IIRC the 2.3 and 2.4 docs are built on such old versions of Sphinx that they may not support the theme
16:12:02 <gundalow> https://github.com/ansible/ansible/pull/49190 is where the work was done originally
16:12:13 <acozine> I remember that rebuilding them was "a real production number" (in the Busby Berkeley sense)
16:12:42 <felixfontein> gundalow: it's this one: https://github.com/ansible/ansible/pull/76759 (I just see that I have to update it's title)
16:13:04 <gundalow> acozine: oh, are you suggesting might need to upgrade Sphinx *and* theme?
16:13:15 <acozine> possibly, yes
16:13:24 <felixfontein> sounds like 'fun'
16:14:06 <gundalow> urgh, the gift that keeps on giving
16:14:12 <acozine> I can't remember the details, but I do remember that after getting the 2.3 docs to build (which took a couple of days of banging) I wrote an entire document about how to build "ancient" docs
16:14:19 <acozine> and yeah, it was "fun"
16:14:21 <gundalow> Yup, got your doc
16:14:34 * samccann[m] races in late
16:14:42 <gundalow> #chair samccann
16:14:42 <zodbot> Current chairs: acozine briantist felixfontein gundalow samccann
16:14:45 <felixfontein> it might be easier to just un-index the 2.3/2.4 docs by telling search engines via robots.txt that they must not index them
16:14:45 <gundalow> Welcome :(
16:14:49 <gundalow> * Welcome :)
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:32 <acozine> I would vote for adding anything older than 2.5 to the "don't index" list in robots.txt
16:16:26 <acozine> 2.5 is the version where the docs stopped using a flat directory structure and introduced the "guides"
16:16:30 <samccann[m]> our internal search expert has 'opinions' about deindexing. So it's a possibility, but we'll want to explore other options as well
16:16:44 <acozine> ah, that might explain why we didn't do it earlier
16:16:51 <acozine> I know we'd talked about it
16:16:54 * samccann[m] unsure if deindexing is the same as robots.txt
16:17:13 <acozine> and honestly I thought we'd done it, maybe around the time of the 2.9 release
16:17:19 <felixfontein> samccann[m]: I would say it is, but it might be worth to ask what exactly they mean
16:17:54 <samccann[m]> So options are: - fix the theme and republish with cannonical url
16:17:54 <samccann[m]> - deindex
16:17:54 <samccann[m]> - move all the old docs off to some other site (so they still exist, but you gotta make an effort to find them
16:18:12 <acozine> what's our goal?
16:18:36 <gundalow> Google "ansible authorized_key" and the 2.3 docs come up top
16:18:42 <samccann[m]> oh and a last explosive option - redirect them entirely (which is very close to just yanking them down since they would become inaccessible
16:19:27 <samccann[m]> #info we still have problems with older docs coming up first in search results (eg google "ansible authorized_key" and you get 2.3 or 2.4 at the top results)
16:19:33 <acozine> gundalow: so the goal is "make sure google results don't return 2.3 documentation
16:19:55 <samccann[m]> I'd vote for google shouldn't return anything under ssay ...2.7
16:20:00 <acozine> samccann: is there a second part to that goal? something like "without doing the thing our search person thinks woudl be a bad idea"?
16:20:04 <acozine> whatever that is?
16:20:31 <samccann[m]> I think we need to decide what the bad ideas are, yes
16:20:42 <samccann[m]> so is redirect so no one ever finds 2.3 a bad idea?
16:20:45 <acozine> because if "make sure google results don't return 2.3 docs" is the goal, then `robots.txt` is the answer,
16:21:07 <acozine> samccann: I'd say we need to solve the google problem first
16:21:45 <samccann[m]> Well it also solves the google problem
16:22:00 <samccann[m]> that's my point. We have multiple possible fixes. Can we eliminate some?
16:22:36 <acozine> I'm not sure, it might just mean that folks get a google result that takes them to 2.3, and then get redirected to . . . well, whatever we put in
16:23:38 <acozine> if we're going to delete the 2.3 docs and redirect those URLs, telling google to stop indexing them first will give us the cleanest transition, I think
16:23:49 <samccann[m]> i think in that instance, google would eventually learn and stop serving up 2.3.
16:24:34 <samccann[m]> I can go back to our search expert with different ideas. I just want to know - is taking down/redirecting 2.3 a viable option? I have been thinking no, that there are users still on that release, even if it's ancient and EOL'd
16:25:12 <acozine> taking 2.3 docs down and redirecting them first might work - to me it feels like more work and potentially a worse user experience
16:25:40 <acozine> if we can get search results down first, then maybe we can redirect `2.3/*` to a single page
16:26:09 <acozine> instead of crafting individual redirects the way we did with the 2.9/2.10 transition
16:27:06 <samccann[m]> oh yeah wasn't going to do fancy redirects. I can't even craft a basic one myself, so would be looking for some big gun redirect or something. But at least you and I agree that we don't want to make 2.3 docs completely inaccessable for now
16:27:43 <samccann[m]> PROPOSAL: Our goal is to limit search results to very old ansible releases (2.3-2.7)
16:27:48 <samccann[m]> Is that accurate? ^^
16:28:04 <samccann[m]> haha gosh that could be read both ways. lemme try again
16:28:14 <acozine> heh
16:28:27 <gundalow> oooh, I copied the theme from 2.5 to 2.3
16:28:28 <gundalow> `<link rel="canonical" href="https://docs.ansible.com/ansible/latest/airbrake_deployment_module.html"/>`
16:28:42 <samccann[m]> PROPOSAL: Prioritize search results to /latest/ and limit the number of times that ancient releases show up on the top hits (1-5)
16:28:47 <acozine> gundalow: does it build locally?
16:29:22 <gundalow> it's building, and got the canonical URL in. Still building, so it's possible CSS might be messed up
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:21 <gundalow> hum, and I notice that the links don't work (maybe we are missing redirects?)
16:30:28 <acozine> do we still have redirects in `latest` from the old URLs to the new ones? like from `/become.html` to `/user_guide/beome.html`?
16:30:30 <gundalow> oh, that's fixed in a later stable branch
16:31:39 <gundalow> full disclaimer: I just deleted some random directories from 2.3 and copied some from 2.5, and hacked the conf.py. There is likely more to be done
16:32:05 <acozine> my vote would be, go back to the search expert and propose adding the 2.3-2.4 docs to "do not index" in the `robots.txt`, see what he says
16:32:49 <acozine> before spending too much time and effort updating something we don't really want people to find
16:33:10 <samccann[m]> do we continue the work gundalow is doing to get canonical url in 2.3 ?
16:33:48 <acozine> I wouldn't bother, unless it turns out there's a really good reason not to exclude those old docs from the search index
16:34:22 <acozine> I admit I'm influenced by the recollection that working on those older docs was a real PITA
16:34:43 <gundalow> The change https://github.com/ansible/ansible/compare/stable-2.3...gundalow:2.3canonical_url?expand=1#diff-de16707d76a94c258b2d4ba2b8f95910db018b923e2b4834dacf47c8964b2a90L125
16:35:02 <samccann[m]> that said, it may take time to get help from the search expert so maybe we try both options in the background (talk to search expert about robots, figure out what wild west canonical url stuff gundalow is up to :-)
16:35:28 <acozine> sure
16:35:40 <acozine> see if gundalow's change will build to the test site
16:36:03 <samccann[m]> i have to create a new jenkins job for the ancient docs first, then we can try his PR
16:36:43 <samccann[m]> meanwhile I can open a ticket on the internal.. erf. ticket tracking thingy to get help from the search expert. (forgot the name of t he tracking system)
16:37:30 <samccann[m]> #action samccann to book time with search expert to help us reduce search results to ancient docs
16:37:49 <samccann[m]> #action samccann gunalow - get his cannonical url for 2.3 work staged on test etc
16:38:40 <samccann[m]> anything else on this topic before we move on?
16:38:50 <gundalow> Sounds good, thanks
16:38:51 <gundalow> oh
16:39:15 <gundalow> #action gundalow to look if redirects are broken
16:39:19 <gundalow> nothing else
16:39:58 <samccann[m]> cool thanks
16:40:06 <samccann[m]> #topic DocTools updates
16:40:15 <felixfontein> sorry, been a bit afk... I agree with acozine that 'taking 2.3 docs down and redirecting them first might work - to me it feels like more work and potentially a worse user experience'
16:40:16 <samccann[m]> Do we have felixfontein today?
16:40:55 <samccann[m]> heh ok looks like we have a new `antsibull` release, right? so I need to test and then update the known_good requirements file?
16:41:05 <felixfontein> samccann[m]: I already updated it in the PR ;)
16:41:24 <felixfontein> samccann[m]: https://github.com/ansible/ansible/pull/76759  - the title is wrong, it should say "0.41.0" instead of "0.40.2"
16:41:25 <samccann[m]> lol cool. I'll stage it to test and see how things go!
16:41:53 <samccann[m]> #action samccann to test https://github.com/ansible/ansible/pull/76759 for the updated antsibull release
16:42:31 <samccann[m]> What was the .40.1 change do you remember?
16:42:42 <samccann[m]> So we can look for both once I stage it to teset
16:42:48 <samccann[m]> s/teset/test/
16:43:15 <felixfontein> 0.40.1 -> 0.40.2 was fixing some broken HTML
16:43:31 <felixfontein> https://github.com/ansible-community/antsibull/issues/386
16:43:37 <samccann[m]> and 40.0 -> 0.40.1?
16:44:04 <felixfontein> I think that was a fix because 0.40.0 crashed somewhere during docs build :)
16:44:19 <samccann[m]> #info 0.40.1 -> 0.40.2 fixes broken HTML - https://github.com/ansible-community/antsibull/issues/386
16:44:24 <samccann[m]> heh
16:44:28 <samccann[m]> ok thanks!
16:44:34 <felixfontein> https://github.com/ansible-community/antsibull/releases/tag/0.40.1 says "Fix bug in collection enum for docs generation, which caused role FQCNs to be mangled (#379)."
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:04 <samccann[m]> #info 0.40 to 0.40.1 - https://github.com/ansible-community/antsibull/releases/tag/0.40.1
16:45:10 <samccann[m]> just so I remember what to look for
16:45:22 <felixfontein> details for that were in https://github.com/ansible/ansible/pull/76675
16:45:35 <felixfontein> that upgraded from 0.39.2 to 0.40.1
16:45:39 <samccann[m]> #link https://github.com/ansible/ansible/pull/76675
16:47:17 <samccann[m]> ok gonna open the floor
16:47:22 <samccann[m]> #topic OpenFloor
16:47:32 <briantist> I have two docs-build related things that could use a look:
16:47:32 <briantist> - a PR that closes 3 open issues, adding support for both more lenient, and more strict docs builds, and specifying a specific antsibull version (all helpful for expanding the scope of scenarios for building docs: https://github.com/ansible-community/github-docs-build/pull/27
16:47:32 <briantist> - a comment on an open issue with an idea of how to solve a tricky problem around the shared GitHub workflows referencing the actions in a consistent way (this is more in the weeds of GHA stuff, not so interesting around docs directly): https://github.com/ansible-community/github-docs-build/issues/4#issuecomment-1024974751
16:47:36 <samccann[m]> This is the time to bring up anything on your mind about docs.
16:48:16 <samccann[m]> #info looking for feedback - PR that closes 3 open issues, adding support for both more lenient, and more strict docs builds, and specifying a specific antsibull version (all helpful for expanding the scope of scenarios for building docs: https://github.com/ansible-community/github-docs-build/pull/27
16:48:38 <samccann[m]> #info also looking for feedback on a comment on an open issue with an idea of how to solve a tricky problem around the shared GitHub workflows referencing the actions in a consistent way (this is more in the weeds of GHA stuff, not so interesting around docs directly): https://github.com/ansible-community/github-docs-build/issues/4#issuecomment-1024974751
16:50:09 <felixfontein> the next big antsibull docs-related thing will probably be extra links
16:50:22 <samccann[m]> Greg's stuff?
16:50:38 <felixfontein> yes :)
16:50:50 <gwmngilfen-work> i wrote the todos!
16:50:59 <samccann[m]> HAH dude has a ping on his name, totally has a ping on his name
16:51:06 <gwmngilfen-work> yep
16:51:19 <samccann[m]> :-) and here I was trying not to disturb you!
16:51:41 <felixfontein> next time it's Mr G. ;)
16:51:58 <samccann[m]> reminds me of my frequent typing of `dagnammit` in this channel (with a space) and mistakenly pinging dag$
16:52:04 <acozine> heh
16:52:05 <samccann[m]> LOL Mr G!!
16:52:59 <samccann[m]> ok I glanced briefly at your prs briantist and they are zooooooming way to far over my head. So hoping others will take a look etc
16:53:09 <samccann[m]> s/to/too/
16:53:30 <samccann[m]> do we have other open floor topics to discuss today?
16:53:52 <briantist> thanks anyway samccann[m] !
16:54:19 <felixfontein> I'll try to look at them later
16:54:27 <samccann[m]> cool thanks!
16:54:45 <briantist> thank you felixfontein , I know you're particularly overburdened recently
16:54:49 <acozine> I will, too, though not today, and I don't know that I'll have much in the way of feedback
16:55:16 <samccann[m]> anything else before we close the meeting with 4 min to spare?
16:55:40 <briantist> to be clear: the things I linked don't "contain" documentation
16:55:51 <briantist> (nothing else from me on open floor)
16:56:18 <acozine> nothing from me either
16:57:03 <samccann[m]> #endmeeting
16:57:15 <acozine> thanks folks!
16:57:15 <samccann[m]> Thanks everyone and special thanks to gundalow for running!
16:57:32 <felixfontein> hmmmmm
16:57:34 <samccann[m]> hmm...
16:57:43 <felixfontein> I think gundalow #chair'ed your IRC nick, not your matrix nick
16:57:51 <samccann[m]> AAAHAHAH
16:57:58 <felixfontein> so basically everything you #info'ed, #topic'ed, #link'ed didn't got into the minutes
16:58:05 <samccann[m]> so much for those stellar meeting notes.  Can anyone endmeeting for us?
16:58:20 <gundalow> #endmeeting