15:02:33 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:02:33 <zodbot> Meeting started Tue Jul 12 15:02:33 2022 UTC.
15:02:33 <zodbot> This meeting is logged and archived in a public location.
15:02:33 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:02:33 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:02:33 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:41 <samccann> #topic opening chatter
15:02:53 <DonNaro[m]> hellooOoOOoo!
15:02:55 <DonNaro[m]> and welcome back
15:02:56 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:58 <DonNaro[m]> 0/
15:03:01 <DonNaro[m]> o/
15:03:09 <samccann> #chair Don Naro
15:03:09 <zodbot> Current chairs: Don Naro samccann
15:03:10 <samccann> thanks!
15:03: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:04:11 <samccann> https://github.com/ansible/community/issues/643#issuecomment-1168914269  is the agenda
15:04:41 <samccann> could be a quiet one today!
15:05:01 <felixfontein> o/
15:05:02 <samccann> #topic Documentation updates
15:05:11 <samccann> #chair felixfontein
15:05:11 <zodbot> Current chairs: Don Naro felixfontein samccann
15:05:12 <samccann> woot!
15:05:41 <samccann> #topic doctools
15:06:03 <samccann> #info - Can we use redirects based on referrers to redirect old EOL docs to latest?
15:06:43 <samccann> so someone mentioned this idea today - that we could redirect say 2.3 docs to latest, if the referrer is not empty (aka not a bookmark) or not docs.ansble.com (aka not browsing the 2.3 docs).
15:07:12 <samccann> That might save us from having to set up an archive site (other than setting up links to all the old docs on docs.ansible.com.
15:07:28 <samccann> curious what others think?
15:07:31 <acozine> o/
15:07:34 <acozine> sorry I'm late
15:07:43 <samccann> #chair acozine
15:07:43 <zodbot> Current chairs: Don Naro acozine felixfontein samccann
15:08:00 <samccann> no worries... just getting warmed up here
15:08:44 <acozine> if we redirect an entire old docset, does that make the old docs completely unavailable?
15:08:49 <acozine> and if so, are we okay with that?
15:08:57 <felixfontein> how complicated is it to set up such a redirect?
15:09:12 <samccann> no it would mean if you had a direct link bookmarked, it would still work
15:09:50 <acozine> so if you knew a specific page, you could find it in 2.3, but if you just hit the main URL for docs.a.c/ansible/2.3, you get `latest` instead?
15:10:03 <samccann> We would add links on docs.ansible.com to each of the old releases. So people could get there directly from docs.ansible.com, but not from some blog post or stack overflow post. Those would redirect to latest
15:10:15 <felixfontein> acozine: in the second case you'd also end up on the 2.3 docs
15:10:44 <felixfontein> acozine: only if you click a link somewhere else (like in some search results), then you end up with the latest docs
15:10:46 <samccann> acozine: well i'm guessing on this but yeah, if you type in the url it works, or bookmark it, or go to docs.ansible.com and navigate to it, those all still work
15:10:49 <acozine> so the only way to get to the 2.3 docs would be to hit the main docs.a.c/ansible page, then follow a link?
15:10:59 <samccann> or bookmark it, yes
15:11:00 <felixfontein> the disadvantage is that if someone explicitly searches for 2.3 docs, they still end up with latest
15:11:14 <samccann> yep.
15:11:19 <felixfontein> (or copy a link to the clipboard and paste it back into the browser)
15:11:52 <felixfontein> (or install a browser privacy extension that prevents the browser from sending referrers :) )
15:11:57 <samccann> but that search would be the same if we archived the docs (to a different url). At least for a time
15:12:03 <samccann> heh
15:12:08 <felixfontein> yes, definitely
15:12:48 <samccann> so basically we have two options: - 1 - magic redirects or 2 set up an archive site, and still add redirects (old site to latest).
15:13:27 <acozine> what is the problem we're trying to solve?
15:13:55 <samccann> people are still getting 2.3 etc docs as 2nd google search option
15:14:01 <tremble> Please don't do automatic redirects unless you have a perfect 1:1 match.  A vendor does that and redirects to the main landing page.  It's really annoying
15:14:45 <samccann> tremble: yes if it's not 1x1 match, the redirects will go to our cowsay 404 page I think
15:15:11 <samccann> but most if not all of these do redirect well I think. I'll have to verify but they do mostly match
15:17:03 <samccann> so the benefit of magic redirects  - assuming they are easy to create, we get an EOL docs solution fairly quickly.  The drawback - I dunno how a search for 2.3 docs would work.
15:17:16 <samccann> is 'google search' considered a referrer??
15:17:43 <acozine> maybe this is something we could test for a single page, and see how it works "on the ground"?
15:18:00 <samccann> yep we could for sure
15:18:38 <samccann> #action samccann to test one redirect based on referrer for 2.3 and see how it works.
15:18:59 <samccann> #actoin samccann to view 2.3 docs to see how many won't do a 1x1 match to latest
15:20:00 <samccann> is there any benefits to using the archive site instead?  I 'think' that means over time, the 2.3 search results might come back, but would likely be for peopleactually looking for 2.3
15:20:33 <samccann> #action samccann to view 2.3 docs to see how many are not 1x1 match with latest
15:20:47 <samccann> typing for beginners
15:21:28 <DonNaro[m]> I know we've talked about it before but what about instructing google, et al, not to index the old docs? just drive folks to latest that way.
15:22:05 <samccann> that's considered a no-no by our resident search expert in CCS (JP).
15:22:27 <samccann> it basically strips us of our search 'authority' that has built up over the years or something.
15:23:04 <samccann> I think I stumbled on a google search page that said basically the same thing - don't use noindex for stuff like this
15:24:16 <DonNaro[m]> ok. honestly I don't really get the no authority thing, especially if google is still indexing latest.
15:24:41 <felixfontein> search engine optimization is black magic.
15:25:08 <DonNaro[m]> indeed it is. I'm certainly not an authority.
15:25:09 <acozine> I think the reasoning goes like this:  we got "credit" for blog posts that pointed to 2.3 when 2.3 was the latest thing; if we stop indexing that page, we lose that "credit"???
15:25:16 <samccann> heh eggzactly. which is why I follow the internal expert when I can
15:25:18 <felixfontein> if someone figured out that you can improve your search results by dancing around a pole in clockwise order at midnight on full moon, everyone will do it, even though nobody understands why it works ;)
15:25:30 <samccann> yeah it's a buildup of credit aka authority like that
15:25:46 <samccann> felixfontein: HAHAH!
15:25:52 <felixfontein> i.e. basically make sure that blog posts always link to /latest/ :)
15:25:59 * samccann sets alarm for midnight...
15:26:11 <acozine> to be fair, google doesn't really want folks to know, because yeah, anything that will artificially change your search ranking, everyone will do . . . which kinda defeats the point
15:26:32 <felixfontein> acozine: exactly... and fully understandable :)
15:26:59 <samccann> yeah fun fact - I noticed before this meeting that google also decides to ignore the canonical url WE set and pick one of its own.
15:27:23 <acozine> hm, how did you discover that? and what are they using?
15:27:58 <samccann> g-undalow (not to ping him) gave me access to google search console. And it has it listed - user-set canoncial, google's canonical
15:28:55 <samccann> and I saw a 2.3 page that uses 2.4 as the canonical url instead of latest.  and ditto for 2.4  - uses 2.4 as canonical instead of latest set by us.  Google loves 2.4! ;-)
15:29:26 <samccann> ok we probably beat google search fun to death for now.  moving on.
15:29:38 <samccann> #info Do we need to back out the docs override for boolean values? - https://github.com/ansible-community/community-topics/issues/116
15:30:31 <samccann> We talked about this a bit the last time. While other folks can debate truthy fun, I'm inclined to remove the docs override and just put up whatever the collection owner put in place for booleans.
15:30:38 <samccann> 1 - it removes docs from the debate
15:31:06 <samccann> 2 - we weren't doing the override everywhere, so the end result is ...sloppy.  The parameter might have yes/no over ride, but description and examples do not.
15:33:16 <samccann> hmm i'm not hearing any screaming and gnashing of teeth on that proposal... :-)
15:33:17 <samccann> SILENCE IS APPROVAL!
15:33:18 <samccann> heh
15:33:31 <acozine> heh
15:34:10 <acozine> I am by nature a control freak, so I feel the pull of IMPOSING OUR WILL, but it doesn't seem worth it in this case
15:34:51 <felixfontein> ok, I'm off now, conference's over for now. will be back later, but probably not before this meeting is over :)
15:34:58 <tremble> If YAML 1.2 doesn't recognise "yes" and "no", at some point down the line this is going to bite us...
15:35:04 <samccann> thanks felixfontein !
15:35:36 <samccann> tremble: ah good point!
15:35:36 <samccann> That seems the final nail in the docs override coffin to me
15:35:40 <acozine> bye felixfontein!
15:35:44 <felixfontein> about bools: I really like 'true' and 'false', I'm for using them. I think we even once voted that we prefer that anyway, but then there's still the old decision of using 'yes' and 'no'...
15:35:44 <samccann> #info If YAML 1.2 doesn't recognise "yes" and "no", at some point down the line this is going to bite us
15:36:03 <tremble> felixfontein called it out in his comment, I was just reading the issue :)
15:36:27 <samccann> hehe thanks!
15:37:31 <samccann> #action - samccann to back out the docs override for boolean
15:38:13 <tremble> I think most SysAdmins can cope with "True" and "False", I do get the point that "do_something: yes" is a little more user-friendly than "do_comething: True"
15:38:18 <tremble> s/do_comething/do_something/
15:38:35 <acozine> yeah, that was the original thinking ^^^
15:39:19 <acozine> but in a way, using `True` helps people understand how boolean variables work
15:39:34 <acozine> because the variables are not always expressed as `do_something`
15:39:49 <acozine> anyway, +1 for "letting it all hang out" for a while
15:40:01 <samccann> heh
15:40:10 <acozine> we can always reimpose the override if it gets too messy and folks get confused (and tell us about it)
15:41:05 <samccann> heh
15:41:10 <samccann> ok  moving on
15:41:19 <samccann> #topic Docs Updates
15:41:39 <samccann> #info debating where the windows developer guides should be sourced - https://github.com/ansible-collections/community.windows/issues/394 and https://github.com/ansible/community/issues/643#issuecomment-1180358267
15:42:15 <samccann> I think this has simmered down to a 'don't move it' decision. I thought it was specific to the windows collections, but it's more core-focused than I thought.
15:42:16 <samccann> Consensus is leaning toward leave it where it is.
15:43:34 <acozine> that seems reasonable
15:44:30 <acozine> IIRC a lot of the Windows documentation is about setting up connections/auth, so keeping that in the core docs makes sense
15:44:52 <samccann> ok we have a few minutes left to open the floor
15:44:56 <samccann> #topic Open Floor
15:45:18 <samccann> here's the time you can bring up anything about docs
15:46:23 <samccann> Don Naro: anything new in the user guide revamp effort?
15:47:14 <DonNaro[m]> no, unfortunately. I was hoping to get some more work done on that front last week but didn't get to it. I'll be on it again this week though.
15:47:19 <samccann> coolness!
15:47:27 <DonNaro[m]> will be dipping into the playbooks content
15:47:39 <samccann> heh come on in the water's fine!
15:48:13 <samccann> ok if no one has anything else?
15:49:03 <samccann> #endmeeting