15:01:49 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:49 <zodbot> Meeting started Tue Aug  2 15:01:49 2022 UTC.
15:01:49 <zodbot> This meeting is logged and archived in a public location.
15:01:49 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:49 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:49 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:01 <acozine> o/
15:02:01 <samccann> cuz it's about that time!
15:02:10 <samccann> #chair acozine
15:02:10 <zodbot> Current chairs: acozine samccann
15:02:17 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:30 <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:02:48 <samccann> felixfontein: andersson007_  around to chat docs today?
15:03:05 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1195840948
15:04:30 <samccann> #topic Documentation Updates
15:05:10 <samccann> So the usual  - checkout the user guide moves. See https://docs.ansible.com/ansible/devel/index.html for current status. More to come.
15:05:10 <samccann> 
15:05:34 <acozine> Are there open PRs for the User Guide changes?
15:05:57 <samccann> Not right now. Don is on PTO and he's been doing the work
15:05:57 <acozine> gotcha, thanks
15:06:22 <samccann> It's basically just creating separate guides from existing content so it's a bit easier to find sections etc
15:06:45 <samccann> #info accessibility guidelines we should investigate - https://www.ibm.com/able/
15:07:21 <samccann> ^^ that was just passed to me before the meeting as a place we can find resources/tests/checklists etc. I think we have other info around as well
15:07:49 <samccann> gist of it is, we really should hop on that and see where we stand as a docsite...where do we need to put in more work etc to make things more accessible.
15:08:27 <acozine> does that site include some kind of accessibility audit?
15:08:46 <samccann> I think it does somewhere under tools. I saw a plugin for chrome so figured I'd experiment later
15:09:08 <acozine> that sounds great
15:09:29 * samccann squirrels away that url so I don't forget
15:10:45 <acozine> heh
15:10:47 <samccann> #info we are down to 43 docs PRs, 13 docs-only, and 76 docs issues
15:11:00 <acozine> wow, that is fantastic!
15:11:14 <samccann> those PR numbers have been holding steady so to speak. That might be our steady state point so to speak
15:11:45 <acozine> well, you don't want to get to 0
15:11:45 <samccann> it's the docs only I focus on, and of those 13, I think a good chuck (1/3 or more) are WIP and internal RH people.
15:12:02 <acozine> 0 would mean nobody's interested
15:12:13 <samccann> so yeah, I feel like thanks to the help of community-writers folks, we're making a real dent in the backlong
15:13:55 <samccann> #info - if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.
15:14:53 <samccann> so here's an interesting one
15:15:16 <samccann> #info browser back button doesn't seem to work well with version switcher of late.
15:15:33 <samccann> @briantist noticed it and feels like it's something relatively new (past month or so)
15:16:55 <samccann> I gave it a try yesterday and see the same thing. If I switch from say latest to devel on a page w/ the version switcher, it works. But then if I use the browser back button, it doesn't go back  to latest. It goes back to ..erm... some other page before I started using the version switcher.
15:17:29 <samccann> I haven't a clue what controls that behavior, but code-wise, we haven't touched the ansible sphinx theme since Feb, and haven't touched version switcher code for over a year
15:17:42 <acozine> huh
15:18:10 <acozine> I suppose that might be a feature
15:18:38 <samccann> lol not sure he'd agree w/ you on that one
15:18:47 <acozine> if the assumption is that people switch versions because they realize they're looking at the wrong version, maybe the code assumes they want the current version of the previous page?
15:19:01 <acozine> I'm not saying it SHOULD be a feature
15:19:01 <samccann> oh that part works
15:19:34 <samccann> So I brows to docs.ansible.com and eventually to  the latest docs and pick a playbook page
15:19:55 <samccann> then I version switch to devel. I get that playbook page fine
15:20:23 <samccann> but if I hit the back button, I don't go back to that same page on latest. I go back to... maybe whatever the last page I BROWSED to so to speak? not sure the exact pattern
15:21:19 <acozine> oh, so I'm on docs.a.c/ansible/2.9/foo.html, then on docs.a.c/ansible/2.9/bar.html, then on docs.a.c/ansible/latest/bar.html
15:21:25 <acozine> using the version switcher
15:21:39 <samccann> well drop 2.9 since that's eol.
15:21:40 <acozine> and then I hit back and it takes me back to 2.9/foo.html?
15:21:40 <samccann> but yeah
15:21:49 <samccann> it takes you back somwhere
15:22:10 <acozine> that seems wrong
15:22:10 <briantist> hi, I'm here for a short while
15:22:16 <samccann> ok trying this 'live'
15:22:31 <samccann> I browsed my way to https://docs.ansible.com/ansible/latest/community/index.html (via the docs.ansible.com website)
15:22:56 <samccann> now I version-switch to devel and that works - https://docs.ansible.com/ansible/devel/community/index.html
15:23:14 <samccann> now I browser-back button (using chrome) - and I get here - https://docs.ansible.com/ansible/latest/index.html
15:23:31 <samccann> which is the last page I "browsed' to before using  the version switcher.
15:23:40 <samccann> #chair briantist
15:23:40 <zodbot> Current chairs: acozine briantist samccann
15:24:02 <briantist> re: "if the assumption is that people switch versions because they realize they're looking at the wrong version" the reason I often switch versions is that I'm supporting several different versions of Ansible, and especially for 2.9, it's important to see what is or isn't supported between versions, when writing roles/playbooks that need to work across all
15:24:06 <samccann> do you have ideas on what the difference is there? I'm unsure what a browser uses for the back button so to speak
15:24:14 <acozine> hrm, that feels like some kind of redirect thing
15:24:39 <samccann> it's not always back to that page acozine
15:24:48 <briantist> the browser "naturally" fills that in via the sequence of pages you browse; the current behavior seems to indicate that it's using javascript or something to get the other content, and then dynamically writes the content of the page to match
15:25:03 <briantist> so the browser is never told "navigate to a new page" and so it has no extra entry in its history
15:25:15 <briantist> (note: I am not a front-end expert by any stretch)
15:25:35 <acozine> the page you ended up on was the main index page, not the community index page, right?
15:26:02 <samccann> so yes, the version-switcher uses javascrip to hack the url and change latest to devel so to speak. But it's done that for years. nothing new.
15:26:10 <briantist> I suspect previously the version switcher did issue a (client side) redirect, as acozine suggests, and that would've told the browser to navigate to the new page, but that seems not to be the case anymore
15:26:15 <acozine> briantist: I agree, this behavior is not what we want
15:26:36 <samccann> acozine: if I start out on some other page, then navigate to a new page, then version switch. The back button will give me that 'some other page'
15:27:08 <briantist> the page you end up on when you click back is as samccann said, wherever you were before; if you open a new window and go direct, there will be nothing to go "back" to even after the version switch, if that helps visualize this
15:27:19 <samccann> briantist: but I'm lost - how could the version switcher be doing something new when the code hasn't changed in oveer a year?
15:27:35 <acozine> samccann: hm, I thought the links you just posted showed you going to a new page
15:27:48 <acozine> yeah, it's that "the code hasn't changed in a year" thing that makes me suspect redirects
15:27:57 <briantist> well... I am not sure, but it could be a dependency, like a js library it uses? I have very little insight into the front-end components
15:28:24 <briantist> those libraries would get retrieved and loaded at runtime (when the page loads), so you wouldn't "see" it as a code change
15:28:31 <samccann> #info it's possible one of the js dependencies changed?
15:28:59 <briantist> I half-expect someone to come along and say "don't know what you're talking about it's always had this behavior" 😅 but.. I'm pretty sure it wasn't always like this?
15:29:40 <samccann> https://github.com/ansible/ansible/blob/devel/test/sanity/code-smell/docs-build.requirements.txt
15:29:50 <samccann> are the requirments and yeah they don't list js stuffs
15:29:57 <bcoca> briantist: in the end ansbile-doc will always reflect 'current version'
15:30:12 <bcoca> sadly missing a lot of stuff there
15:31:06 <samccann> thinking out loud - if I hack a build to 'bring back' say 2.8, 2.7, I should be able to test this. Those builds have old requirements so in theory, if this worked, it would work w those builds in the version switcher on test, right?
15:31:36 <acozine> possibly
15:31:44 <bcoca> possibly .. but  'do they build?' .. build process has changed and requiers somethings from asnible/ansible to also change
15:31:54 <acozine> though IIRC all the versions in the version-switcher have to use the same code or the switcher itself doesn't work
15:31:55 <briantist> I don't think any JS requirements would be listed in that file, they could seen in the rendered HTML as references, so if those references haven't changed, even an "old" build will have the same front-end behavior
15:31:59 <samccann> @bcoca I think they still build
15:32:00 <bcoca> though pre 2.9 ... the build was IN ansible/ansible
15:32:09 <bcoca> so they should work if you invoke it that way
15:32:14 <acozine> I recall having to backport things a lot at one point
15:32:22 <briantist> does the way-back machine have archives? that could be interesting to see
15:32:31 <acozine> though that was a while back, so maybe I'm misremembering
15:32:31 <samccann> maybe?
15:33:03 <bcoca> http://web.archive.org/web/20220000000000*/docs.ansible.com
15:33:53 <briantist> When I look at this: https://web.archive.org/web/20220111185115/https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/hashi_vault_lookup.html
15:34:27 <briantist> if I change it to 2.9, there's no archive for that, but that I think that's ok: the fact that it tried to change the page means it was a new load by the browser, I think (old behavior I remember)
15:35:13 <briantist> hm, it's hard to tell on these
15:35:41 <briantist> "latest" works, but back button behavior in general on wayback is a little weird, since it brings us back to the calendar
15:36:09 <briantist> so I dunno... inconclusive
15:36:14 <samccann> ok I see the same problem in that example
15:36:34 <samccann> starting at the hashivault. I browsed to the community guide
15:36:35 <samccann> then version switched to devel
15:36:59 * acozine AFK a bit
15:36:59 <samccann> then browser back. Did not take me to community guide, it took me back to hashivault
15:37:18 <briantist> this is on wayback? or current site?
15:37:44 <samccann> on wayback starting tat the url you posted above
15:37:56 <samccann> I figured it must have indexed the ocmmunity guide so it all stayed within the archive
15:37:59 <briantist> hm ok
15:38:36 <samccann> doesn't mean it's not a problem, but does suggest to me it's always been a problem.
15:40:08 <samccann> either way, did you want to open an issue on it? I can't say I can do anything about it, but maybe someone with js skills could look at the version switcher code and figure out why the back browser button doesn't work?
15:40:13 <briantist> yeah.. possibly so. I do agree it IS a problem, I am less trustful of my memory then... I wonder if maybe it was not back/forward that used to work, but that viewing 2.9 used to still show the version dropdown allowing me to get back from 2.9. And maybe with that disappearing I just instinctively went for the browser buttons
15:40:24 <briantist> where is the right place to open the issue?
15:40:30 <samccann> btw - this code I ..ahem.. repurposed from an old WIP PR on the sphinx theme that never go merged.  Might be one of the reasons it never go merged over there
15:41:17 <samccann> sorry yeah we nixed the version switcher from 2.9 because it went EOL a few months back.  Then marketing wanted it back in the devel/latest dropdowns because customers needed a way to find it
15:41:35 <samccann> so it's there, but not on 2.9 docs itself anymore. That likely changed within 2 months
15:41:43 <felixfontein> o/
15:41:51 * samccann still uses the royal 'we' when it's only her now
15:42:09 <samccann> briantist: all that code is still in ansible/ansible so open it there
15:42:15 <briantist> I see, yeah.. timing sounds right.. putting the switcher back in seems like a good idea? not sure that removing the switcher from 2.9 pages helps anything
15:42:15 <samccann> #chair felixfontein
15:42:15 <zodbot> Current chairs: acozine briantist felixfontein samccann
15:42:19 <samccann> welcome!
15:42:32 <briantist> samccann: ok, I will open something there later today
15:42:46 <briantist> I have to drop for now so I still have some time to eat lunch
15:42:47 <samccann> we remove the version switcher from EOL versions because they get outdated FAST
15:43:07 <samccann> so it's part of the EOL effort
15:43:42 <briantist> but how does removing the switcher help? I can see how removing 2.9 from the switcher on newer pages helps people not go to them, but on the old pages, Iw ould think being able to navigate to newer versions would only help people move away from those pages
15:43:48 <samccann> but we can debate this as 2.9 is a bit of a special case... the version thatwould not die :-)
15:43:52 <briantist> as is, they are an island you can't get off of without URL hacking
15:44:16 <samccann> well it was a problem 'in the old days' for sure
15:44:26 * bcoca creates another 2.9 assasination plan
15:44:27 <samccann> but now - we only have devel, latest...
15:44:38 <samccann> so can you open an issue on that one as well pls?
15:44:51 <samccann> so I can point to it when folks ask - why are you cracking open 2.9 AGAIN
15:45:14 <briantist> hmm an issue on what exactly? re-adding version switcher to 2.9 pages?
15:45:21 <samccann> yes pls
15:45:32 <briantist> sure
15:46:44 <samccann> one final think out loud. So if I put back the version switcher in 2.9, it will allow latest, devel, and 2.9.  I don't think that ever gets 'out of date'. It used to be a problem when we had '2.9, 2.8, 2.7' or something because you'd land on the old docs and never get to the new ones so to speak.
15:47:21 <samccann> anyone see holes in that logic?
15:48:06 <briantist> right, that's my thinking as well.. even if 2.9 gets yanked out of the switcher on latest/devel, I'd be fine with having to hack URLs to get to an EoL version's page, I think that's reasonable, but giving an off-ramp to get back to a supported version is only helpful imo
15:48:36 <samccann> yeah makes sense to me now :-)
15:48:53 <bcoca> i would consider makign the 'version switcher' a tool outside the site versioning, so it can handle it universally
15:49:18 <briantist> alright dropping for real now.. thanks for everyone's time!
15:49:24 <samccann> thanks!
15:49:31 <samccann> #topic Open Floor
15:49:38 <bcoca> something that we have long looked at for 'non doc pages'  like 'community communications page' and others
15:49:44 <samccann> anyone have docs thoughts to bring up? now's the chance
15:49:55 <bcoca> ^ i jsut did?
15:50:00 <bcoca> ;-p
15:50:00 <samccann> hahaha
15:50:16 <samccann> you mean unversioned docs? thnings not tied to a core/Ansible version?
15:51:14 <bcoca> yep
15:51:49 <bcoca> mostly pages that are worth next to 0 or even negative if you go back in versions (release schedule, communication channels, policies, etc)
15:52:47 * acozine returns mid-conversation
15:52:54 <acozine> didn't we make some of those pages devel-only?
15:53:10 <samccann> we had to revert that with 2.13 acozine
15:53:29 <acozine> ah
15:53:29 <samccann> people found it confusing that the official page was also the devel page so to speak.
15:53:39 <bcoca> they need to be 'versionless'
15:53:42 <samccann> but the general problem that keeps us from doing this is we don't have a site-search option
15:53:52 <bcoca> well, we do, but it sucks ...
15:53:55 <samccann> if we did, we could have docs.ansible.com/ansible/roadmaps
15:53:59 <samccann> no, we don't
15:54:09 <samccann> we have a VERSION search
15:54:16 <samccann> and even that is only searchign latest
15:54:28 <bcoca> ah, true, we limit it to 'subsite'
15:54:40 <samccann> nothing on docs.ansible.com searches across any subdirs right now
15:54:41 <samccann> yep
15:54:44 <bcoca> but that is not about the search itself
15:55:03 <bcoca> ti does do subdirs, but we set the level 'after version' not before it
15:55:16 <samccann> well it is in the sense that it was considered THE MAJOR blocker to having separate subsites
15:55:22 <bcoca> which can be confusing, since we really need 'per version when version exists, global but ignore other versions when it doesnt'
15:55:26 <samccann> what search are you talking about? pointer pls
15:55:54 <bcoca> its not really just 'move it up one scope' but 'move up and ignore versioned that are not me'
15:56:32 <samccann> yeah the gist of it is, we don't have the solution so we can't split things to subsites.
15:56:43 <samccann> solvable problem for sure, but no one around to solve it right now
15:57:04 <bcoca> team keeps shirnking while work keeps expanding .. totally sustainable!
15:57:52 <bcoca> wish i had time to help, it should not be too hard to do, but it does require a good ammount of time and reworking many things
15:58:45 <samccann> heh thanks
15:59:00 <samccann> ok we have 2 min left, anything else to add before we close the meeting?
16:00:49 <samccann> #endmeeting