15:00:42 #startmeeting Documentation Working Group aka DaWGs 15:00:42 Meeting started Tue May 2 15:00:42 2023 UTC. 15:00:42 This meeting is logged and archived in a public location. 15:00:42 The chair is oranod. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 15:00:42 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:00:42 The meeting name has been set to 'documentation_working_group_aka_dawgs' 15:00:57 👋 15:01:10 @room Let's meet! Who is here to talk about docs? 15:01:16 hey Pelisse Romain 15:01:20 o/ 15:01:31 #chair Pelisse Romain 15:01:31 Current chairs: Pelisse Romain oranod 15:01:57 To any newcomers - again, welcome. We chair all attendees as a way of recognizing your time spent here. And it opens it up for people to add to the meeting minutes with commands like #info or #link (to add a link) 15:02:05 If you wish to join us, please raise your hand (o/) and say hi. 15:02:24 to add to the meeting minutes with commands like #info or #link (to add a link) 15:02:24 General run of the meeting - We go over action items, give docs updates.. maybe have a topic or two, and go over doctooling updates (all the fun stuff behind the scenes that get us docs.ansible.com!) 15:02:28 s/to add to the meeting minutes with commands like #info or #link (to add a link)// 15:02:40 #info meeting agenda at https://github.com/ansible/community/issues/678#issuecomment-1522054412 15:03:36 o/ 15:03:48 samccann: won't be joining us today for personal reasons (she's fine though) so I'll be doing my best to fill in for her and run the meeting 15:03:59 #chair acozine 15:03:59 Current chairs: Pelisse Romain acozine oranod 15:04:15 #topic Action Items 15:05:58 #info I'll start with myself, last week I took away an action to gather some issues for contributors related to the docsite and the Ansible Middleware collections. still working through them - lots of distractions and PTO last week - but plan to have a PR for the mw collections site today that will explain how contributors can get involved with those docs 15:06:14 I'll ping you when that PR is up Pelisse Romain 15:07:08 #info for docsite contributions, I've found a few gaps and other bits where doc contributors can get involved but the tricky part is describing that clearly lol but I'm working on it 15:07:51 on a side note it will help a lot when we have a forum and more of a central wiki where we can put resources to help folks get involved with the docs 15:08:33 yeah, the forum will help 15:09:52 it really will. the community team has been working towards creating toolkits for various sorts of contributors and meetup organizers, etc. it'll be great once we're up and running with those so we can just point interested people to the toolkits. 15:11:37 #info docsite status. unfortunately, with samccann away, I don't have any metrics to really look at and give an update here but I think we're pretty much in maintaining without straining mode. 15:12:10 last time she got some stats it looked like there was a noticeable drop in people toggling to the old docsite 15:12:56 one thing I noticed, and would like to maybe get some thoughts on, are some of the pages that we didn't update on the web server 15:13:01 hang on and I'll grab a link... 15:14:35 here we go: https://docs.ansible.com/ansible_community.html 15:15:10 wait, I'd better tag this for the meeting minutes 15:15:32 #info there are some pages still left on the web server that don't use the new layout, such as https://docs.ansible.com/ansible_community.html 15:16:35 #info we've talked about creating stub pages that direct users to the homepage and some text like "update your bookmarks" because any hits to that page would come from users who have it in their bookmarks 15:17:07 #info alternatively we've discussed just nuking the phantom pages and setting up redirects instead 15:18:27 #info there are maybe one or two other pages as well, such as https://docs.ansible.com/ansible-tower/, that we need to update (even though I think the source is lost to time) 15:18:37 anyone have thoughts? 15:18:52 do we have a similar page in the new layout? something with a bunch of links for community docs? 15:19:08 or is the new homepage the current equivalent? 15:19:46 the new homepage is the current equivalent and should help you find your way to the same set of links 15:20:42 the biggest omission I see is the Japanese translations 15:20:44 those are on the old page, but not on the new 15:21:02 https://docs.ansible.com/core.html 15:21:13 I think you'd find those on the Ansible Core page 15:21:34 things are re-organized a little though 15:21:40 I'm thinking of what users would expect if they get redirected 15:22:10 why would someone bookmark that particular page, and would they be surprised to be rediirected to the new home page 15:22:33 as part of thinking about stubs vs. redirects 15:23:21 what is the path from the new home page to that Core page? 15:23:42 it's on the subnav at the top. 15:24:06 ah 15:24:12 unfortunately we couldn't change the top level nav but "Ansible Core" is one of the main nav items 15:24:42 yeah, that's a little odd 15:25:14 because part of the top-level nav reflects the sections in the main pane (Users, Developers, Maintainers) but part of it doesn't 15:25:25 I am speculating but I think the motivation for bookmarking that page is that it kind of points to all the community docs instead of the old homepage, which is a little more of a hodgepodge of community, platform, and the collections card (which is kind of outdated) 15:27:42 What would you think of adding two new quicklinks - one to Ansible Core docs home (to mirror the Package docs home) and one to Translations? 15:28:12 I'm not sure we have a translations central page 15:29:27 I think a quicklink to Ansible Core docs would be a little redundant if it's already in that "sub nav". also we've tried to make the quicklinks point to the top rated doc urls based on analytics that samccann has gathered 15:30:48 we don't have a central page for translations and I think only Core and Controller docs are available in Japanese. but I believe there are plans to increase the number of translations. 15:32:01 many of the links are redundant with the sub nav 15:32:46 that said, it was only a suggestion 15:34:27 it's certainly worth considering that, thanks for bringing it up. I hope we can continue to improve the nav. I'll admit I'm not really so pleased with the subnav but we had to keep the top-level nav consistent with the rest of ansible.com 15:34:51 that'll get better over time 15:36:06 #info Ansible Sphinx theme needs some love. I noticed in a separate chat the other day that some teams are dropping the Ansible Sphinx theme after we applied it because it lacks functionality and the resulting output looks wonky or is missing things. 15:36:33 is there a ticket with details of what's missing or broken? 15:37:41 #info there are issues for the Ansible Sphinx theme here: https://github.com/ansible-community/sphinx_ansible_theme/issues including the issue to create a new theme, which will solve most - if not all - of the problems teams are facing 15:38:02 #info I think the main problem right now is the version of Sphinx that the theme supports is quite low 15:39:13 that makes sense 15:39:27 it probably hasn't been updated in quite a while 15:39:30 other than what's there, which I think we've discussed before, I didn't get a whole lot of detail on what was actually broken. it just brought the need for a new theme to mind. 15:44:18 #topic Open Floor 15:44:32 let's open it up if anyone has something they want to talk about 15:44:58 anyone out there got stuff on their mind or something to share? 15:46:00 (nop, i'm good :) ) 15:50:09 nothing springs to mind 15:50:42 ok let's call it then if nothing much left to discuss. thanks everyone! 15:50:42 #endmeeting