15:01:49 #startmeeting Documentation Working Group aka DaWGs 15:01:49 Meeting started Tue Aug 2 15:01:49 2022 UTC. 15:01:49 This meeting is logged and archived in a public location. 15:01:49 The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 15:01:49 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:01:49 The meeting name has been set to 'documentation_working_group_aka_dawgs' 15:02:01 o/ 15:02:01 cuz it's about that time! 15:02:10 #chair acozine 15:02:10 Current chairs: acozine samccann 15:02:17 @room Meeting time! Who is here to talk the docs? 15:02:30 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 felixfontein: andersson007_ around to chat docs today? 15:03:05 Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1195840948 15:04:30 #topic Documentation Updates 15:05:10 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 15:05:34 Are there open PRs for the User Guide changes? 15:05:57 Not right now. Don is on PTO and he's been doing the work 15:05:57 gotcha, thanks 15:06:22 It's basically just creating separate guides from existing content so it's a bit easier to find sections etc 15:06:45 #info accessibility guidelines we should investigate - https://www.ibm.com/able/ 15:07:21 ^^ 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 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 does that site include some kind of accessibility audit? 15:08:46 I think it does somewhere under tools. I saw a plugin for chrome so figured I'd experiment later 15:09:08 that sounds great 15:09:29 * samccann squirrels away that url so I don't forget 15:10:45 heh 15:10:47 #info we are down to 43 docs PRs, 13 docs-only, and 76 docs issues 15:11:00 wow, that is fantastic! 15:11:14 those PR numbers have been holding steady so to speak. That might be our steady state point so to speak 15:11:45 well, you don't want to get to 0 15:11:45 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 0 would mean nobody's interested 15:12:13 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 #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 so here's an interesting one 15:15:16 #info browser back button doesn't seem to work well with version switcher of late. 15:15:33 @briantist noticed it and feels like it's something relatively new (past month or so) 15:16:55 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 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 huh 15:18:10 I suppose that might be a feature 15:18:38 lol not sure he'd agree w/ you on that one 15:18:47 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 I'm not saying it SHOULD be a feature 15:19:01 oh that part works 15:19:34 So I brows to docs.ansible.com and eventually to the latest docs and pick a playbook page 15:19:55 then I version switch to devel. I get that playbook page fine 15:20:23 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 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 using the version switcher 15:21:39 well drop 2.9 since that's eol. 15:21:40 and then I hit back and it takes me back to 2.9/foo.html? 15:21:40 but yeah 15:21:49 it takes you back somwhere 15:22:10 that seems wrong 15:22:10 hi, I'm here for a short while 15:22:16 ok trying this 'live' 15:22:31 I browsed my way to https://docs.ansible.com/ansible/latest/community/index.html (via the docs.ansible.com website) 15:22:56 now I version-switch to devel and that works - https://docs.ansible.com/ansible/devel/community/index.html 15:23:14 now I browser-back button (using chrome) - and I get here - https://docs.ansible.com/ansible/latest/index.html 15:23:31 which is the last page I "browsed' to before using the version switcher. 15:23:40 #chair briantist 15:23:40 Current chairs: acozine briantist samccann 15:24:02 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 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 hrm, that feels like some kind of redirect thing 15:24:39 it's not always back to that page acozine 15:24:48 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 so the browser is never told "navigate to a new page" and so it has no extra entry in its history 15:25:15 (note: I am not a front-end expert by any stretch) 15:25:35 the page you ended up on was the main index page, not the community index page, right? 15:26:02 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 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 briantist: I agree, this behavior is not what we want 15:26:36 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 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 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 samccann: hm, I thought the links you just posted showed you going to a new page 15:27:48 yeah, it's that "the code hasn't changed in a year" thing that makes me suspect redirects 15:27:57 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 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 #info it's possible one of the js dependencies changed? 15:28:59 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 https://github.com/ansible/ansible/blob/devel/test/sanity/code-smell/docs-build.requirements.txt 15:29:50 are the requirments and yeah they don't list js stuffs 15:29:57 briantist: in the end ansbile-doc will always reflect 'current version' 15:30:12 sadly missing a lot of stuff there 15:31:06 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 possibly 15:31:44 possibly .. but 'do they build?' .. build process has changed and requiers somethings from asnible/ansible to also change 15:31:54 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 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 @bcoca I think they still build 15:32:00 though pre 2.9 ... the build was IN ansible/ansible 15:32:09 so they should work if you invoke it that way 15:32:14 I recall having to backport things a lot at one point 15:32:22 does the way-back machine have archives? that could be interesting to see 15:32:31 though that was a while back, so maybe I'm misremembering 15:32:31 maybe? 15:33:03 http://web.archive.org/web/20220000000000*/docs.ansible.com 15:33:53 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 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 hm, it's hard to tell on these 15:35:41 "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 so I dunno... inconclusive 15:36:14 ok I see the same problem in that example 15:36:34 starting at the hashivault. I browsed to the community guide 15:36:35 then version switched to devel 15:36:59 * acozine AFK a bit 15:36:59 then browser back. Did not take me to community guide, it took me back to hashivault 15:37:18 this is on wayback? or current site? 15:37:44 on wayback starting tat the url you posted above 15:37:56 I figured it must have indexed the ocmmunity guide so it all stayed within the archive 15:37:59 hm ok 15:38:36 doesn't mean it's not a problem, but does suggest to me it's always been a problem. 15:40:08 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 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 where is the right place to open the issue? 15:40:30 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 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 so it's there, but not on 2.9 docs itself anymore. That likely changed within 2 months 15:41:43 o/ 15:41:51 * samccann still uses the royal 'we' when it's only her now 15:42:09 briantist: all that code is still in ansible/ansible so open it there 15:42:15 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 #chair felixfontein 15:42:15 Current chairs: acozine briantist felixfontein samccann 15:42:19 welcome! 15:42:32 samccann: ok, I will open something there later today 15:42:46 I have to drop for now so I still have some time to eat lunch 15:42:47 we remove the version switcher from EOL versions because they get outdated FAST 15:43:07 so it's part of the EOL effort 15:43:42 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 but we can debate this as 2.9 is a bit of a special case... the version thatwould not die :-) 15:43:52 as is, they are an island you can't get off of without URL hacking 15:44:16 well it was a problem 'in the old days' for sure 15:44:26 * bcoca creates another 2.9 assasination plan 15:44:27 but now - we only have devel, latest... 15:44:38 so can you open an issue on that one as well pls? 15:44:51 so I can point to it when folks ask - why are you cracking open 2.9 AGAIN 15:45:14 hmm an issue on what exactly? re-adding version switcher to 2.9 pages? 15:45:21 yes pls 15:45:32 sure 15:46:44 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 anyone see holes in that logic? 15:48:06 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 yeah makes sense to me now :-) 15:48:53 i would consider makign the 'version switcher' a tool outside the site versioning, so it can handle it universally 15:49:18 alright dropping for real now.. thanks for everyone's time! 15:49:24 thanks! 15:49:31 #topic Open Floor 15:49:38 something that we have long looked at for 'non doc pages' like 'community communications page' and others 15:49:44 anyone have docs thoughts to bring up? now's the chance 15:49:55 ^ i jsut did? 15:50:00 ;-p 15:50:00 hahaha 15:50:16 you mean unversioned docs? thnings not tied to a core/Ansible version? 15:51:14 yep 15:51:49 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 didn't we make some of those pages devel-only? 15:53:10 we had to revert that with 2.13 acozine 15:53:29 ah 15:53:29 people found it confusing that the official page was also the devel page so to speak. 15:53:39 they need to be 'versionless' 15:53:42 but the general problem that keeps us from doing this is we don't have a site-search option 15:53:52 well, we do, but it sucks ... 15:53:55 if we did, we could have docs.ansible.com/ansible/roadmaps 15:53:59 no, we don't 15:54:09 we have a VERSION search 15:54:16 and even that is only searchign latest 15:54:28 ah, true, we limit it to 'subsite' 15:54:40 nothing on docs.ansible.com searches across any subdirs right now 15:54:41 yep 15:54:44 but that is not about the search itself 15:55:03 ti does do subdirs, but we set the level 'after version' not before it 15:55:16 well it is in the sense that it was considered THE MAJOR blocker to having separate subsites 15:55:22 which can be confusing, since we really need 'per version when version exists, global but ignore other versions when it doesnt' 15:55:26 what search are you talking about? pointer pls 15:55:54 its not really just 'move it up one scope' but 'move up and ignore versioned that are not me' 15:56:32 yeah the gist of it is, we don't have the solution so we can't split things to subsites. 15:56:43 solvable problem for sure, but no one around to solve it right now 15:57:04 team keeps shirnking while work keeps expanding .. totally sustainable! 15:57:52 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 heh thanks 15:59:00 ok we have 2 min left, anything else to add before we close the meeting? 16:00:49 #endmeeting