16:01:53 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:01:53 <zodbot> Meeting started Tue Mar 14 16:01:53 2023 UTC.
16:01:53 <zodbot> This meeting is logged and archived in a public location.
16:01:53 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:01:53 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:53 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:02:01 <samccann> #chair acozine
16:02:01 <zodbot> Current chairs: acozine samccann
16:02:04 * acozine AFK two minutes for tea & biobreak
16:02:08 <samccann> @room Meeting time! Who is here to talk the docs?
16: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!
16:02:32 <samccann> 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)
16:02:44 <samccann> 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!)
16:03:54 <samccann> #info initial version of a mkdocs Ansible theme in the works but mkdocs may be problematic for a multisite docs build. See https://github.com/facelessuser/pymdown-extensions/issues/1986 samccann
16:04:01 <samccann> ok dunno why that had my name it it, but anyway
16:04:11 <samccann> didn't want to lose the pre-meeting chatter
16:05:01 <samccann> felixfontein: briantist - you around to talk the docs today?
16:05:44 <samccann> #info official agenda at https://github.com/ansible/community/issues/678#issuecomment-1458651403
16:05:53 <samccann> #topic Action Item updates:
16:06:05 <samccann> #info open samccann to create a list of 'docs stuff that needs updating for new release' to catch things like roadmap updates early on.
16:06:25 <samccann> #info closed samccann to review top page hits and add to https://github.com/ansible/jinja-docsite/issues/35
16:06:42 * acozine is back at the keyboard
16:07:10 <samccann> woot
16:07:18 <samccann> #topic personas and revamping the docsite
16:07:46 <samccann> So this is the big thing today. We're close to the point where we will want to replace existing docs.ansible.com pages with the new journey-based pages
16:07:57 <samccann> #info see https://ansible.github.io/jinja-docsite/ for current prototype pages. This will be the new pages soon on docs.ansible.com so feedback needed on this!
16:08:28 <samccann> #info log issues or maybe fix a  few at https://github.com/ansible/jinja-docsite/blob/devel/CONTRIBUTING.md
16:09:21 <acozine> Looks like there are 4 open PRs
16:09:42 <acozine> do they address some of the open issues?
16:10:31 <acozine> also, it looks like there were links on the old pages that don't exist on the prototype new pages
16:10:45 <samccann> yes I think each one tackles an issue, but they are feature-adds mostly. The community page, the footer, and moving core and collections from a page to an item on the ecosystem page for example
16:11:09 <samccann> which area of links acozine ?
16:11:52 <acozine> I'm looking at https://docs.ansible.com/ecosystem.html right now
16:12:38 <samccann> hmm looks to me like they are all at https://ansible.github.io/jinja-docsite/ecosystem.html?
16:13:14 <acozine> how do I get from the homepage to that page?
16:13:30 <samccann> top nav bar
16:13:31 <acozine> oh, i see, I have to select the link in the header
16:13:58 <acozine> that's . . . weird
16:14:38 <samccann> yeah a few things are up there. I think the blog link goes away for now until the new potential website, but ecosystem and community pages will link from up there
16:15:00 <samccann> it's different, but I think people will get used to important things in the top nav..and..less important..in the footer so to speak
16:15:05 <acozine> What is the top nav bar selection for the main page?
16:15:36 <samccann> Ansible documentation
16:16:04 <acozine> I'm trying to figure out how to express the dissonance I'm feeling. There's an expectation in my mind that this design is not meeting.
16:16:21 <acozine> I will try to tease out what it is . . .
16:17:20 <acozine> I guess the question is, does "Ansible documentation" include the whole ecosystem? Or is "Ansible documentation" purely for command-line Ansible?
16:17:37 <samccann> Ansible documentation is the whole ecosystem
16:17:45 <samccann> which is a change, yes
16:18:15 <acozine> if it's the whole ecosystem, then I'd expect the main page to reflect more of the other stuff
16:18:17 <acozine> does that make sense?
16:18:41 <acozine> right now everything in the main pane of hte main page is related to command-line ansible, as far as I can tell
16:19:22 <samccann> ah I see what you are saying
16:19:42 <samccann> earlier drafts had more of the experience beyond core/collections. But that got the wall-of-text feedback so this one is trimmed down
16:20:04 <samccann> but yeah, it means we still have work to do on the journey that gets users/devs beyond core/collections
16:20:30 <acozine> I think a main page with the same links as the top nav, and an addition to both for "command-line Ansible" or however we want to express that concept
16:20:36 <acozine> literally a landing page
16:21:00 <acozine> would make more sense to me
16:21:22 <samccann> I think there are subpages but I'm forgetting how to access them...gimme a sec
16:21:41 <acozine> either that or "downgrade" the status of the "Ansible documentation" link so it's obvious it's one among several
16:21:47 <samccann> https://ansible.github.io/jinja-docsite/user.html
16:22:09 <samccann> so under 'find more resources' on each of the main page sections, link to a subpage
16:22:13 <samccann> that has more of the rest of the ecosystem so to speak
16:22:45 <acozine> wait, how would I get to that page from the main page?
16:23:09 <acozine> oh, the link text is "find more resources for using Ansible"?
16:23:16 <acozine> that's not what I would expect either
16:23:26 <samccann> yep. that's under three of the four main page 'sections' so to speak
16:23:45 <acozine> again, it's the question of what we mean when we say the word Ansible
16:24:11 <samccann> #info docsite feedback - main page is still very Ansible-core focused and links to 'other resources' is less obvious that it brings you to a new page with more details on the journey so to speak
16:24:31 <samccann> Okay so Ansible community is the entire community of ansible projects
16:24:52 <samccann> but yes, we have a problem with that term meaning different things to different people
16:25:30 <samccann> #info the term Ansible is overloaded. Does it really reflect things like navigator, awx etc etc?
16:26:18 <acozine> another thing I see is that the site design has a weird overlap when resizing - between full-size and small-size, you get text over the graphics
16:26:33 * acozine uploaded an image: (51KiB) < https://libera.ems.host/_matrix/media/v3/download/ansible.im/d040630194dc936a568f6d824173822eaab1084d/Screen%20Shot%202023-03-14%20at%2011.25.09%20AM.png >
16:27:18 <samccann> yeah I think there is a responsive design issue there ...
16:27:43 <samccann> https://github.com/ansible/jinja-docsite/issues/31
16:28:02 <samccann> so do you think that is a blocker (responsive design) before we go live?
16:30:27 <acozine> yes, I would consider it a blocker
16:30:43 <acozine> that looks terrible - very unprofessional
16:31:17 <samccann> ok I created a label MVP - corp speak for minimum viable project so to  speak
16:31:31 <acozine> and i'm not on a tablet or phone, just resizing my browser window
16:31:46 <samccann> Don can't be here today but I can go over the issues list based on what we say here etc
16:32:10 <samccann> So maybe that's a good conversation to have - what would we consider the minimum that has to happen to this prototype before it goes live?
16:32:37 <samccann> The goal is to replace the existing pages, but have a link to the 'old' pages for a time and we can see how many people flip to the old etc
16:33:51 <samccann> let me dig up some stats on how many people go to this main page etc. might help us... just a sec
16:34:27 <samccann> dag nammit
16:34:45 <samccann> Adobe analytics is dead. I want to say there's well over 1K hits a day
16:35:02 <samccann> but it could be more like 10k?  Anyway, thousand or more hits every day
16:36:44 <samccann> so for the minumum, this new docsite needs to:
16:37:10 <samccann> 1 - have a new 'place' for all the existing pages.  Some of those new places might be the ecosystem page, other's have real pages so to speak
16:37:30 <samccann> 2 - fix basic responsive design issues
16:37:53 <samccann> I'm thinking the fact that it's still not obvious this is for all Ansible projects isn't a blocker because the old pages are also..not..obvious about this?
16:39:20 <samccann> 3 - translation and prior version stuff has to work (core and controller)
16:39:54 <acozine> I've looked at the site a bit here and there, but I have not gone through it pretending to be a user, much less pretending to be a particular kind of user.
16:40:14 <samccann> so maybe
16:40:20 <acozine> It would be great to get an informal focus group to look at the site, try it out . . .
16:40:51 <samccann> 4. Needs more early-user/tester feedback. maybe a focus group to use it for a time?
16:40:56 <samccann> hmm. should have had infos for all those...
16:41:16 <samccann> #info new docsite needs at least the following before it goes live
16:41:25 <samccann> #info 1 - have a new 'place' for all the existing pages.  Some of those new places might be the ecosystem page, other's have real pages so to speak
16:41:37 <samccann> #info 2 - fix basic responsive design issues
16:41:40 <acozine> well, even 10K hits is pretty small, compared to overall traffic to docs.a.c
16:41:51 <samccann> #info 3 - translation and prior version stuff has to work (core and controller)
16:42:04 <acozine> but it would be good if we could take those hits and use them to educate people and draw them into the community
16:42:23 <samccann> I think at one point I looked and had the number of 10% of our t raffic starts there
16:42:25 <samccann> so if we get 40M hits a year, that's 4M hits on the docs landing pages
16:42:35 <samccann> But I can't find the stats anymore to back that up
16:42:44 <acozine> I was going to say, unless traffic has declined, that's a lot more than 10K hits
16:43:05 <samccann> #info 4. Needs more early-user/tester feedback. maybe a focus group to use it for a time?
16:43:28 <samccann> yeah it likely is when I do the math in revers so to speak
16:43:34 <acozine> especially find some new users to look at the site
16:43:44 <acozine> maybe put a call into the User Help channel?
16:43:46 <acozine> offer some swag?
16:43:54 <acozine> set up a Zoom?
16:44:01 <acozine> something along those lines
16:44:30 <acozine> I wonder if we could have a graphic of "what Ansible means"
16:45:10 <samccann> #info could ask user channel for help, or a live zoom or something...
16:45:10 <acozine> I'm thinking maybe something like concentric circles or a molecular diagram
16:45:11 <acozine> with Ansible Core at the center and the other stuff around it somehow
16:45:18 <acozine> I feel like I've even seen such a graphic
16:45:22 <samccann> There is an issue 'somewhere' to have a good graphic that shows where the components that make up the ecosystem fit to to speak
16:45:37 <acozine> that could be a really great landing page
16:45:45 <samccann> But I think that's targetted for the proposed new website vs this docs page (tho we could repeate it for sure)
16:46:11 <samccann> I think with docs we have to assume a top website page handles that sort of intro to the full Ansible world
16:46:51 <samccann> I think the goal is you get to docs and then are 2-3 clicks from the piece of docs that you need.
16:47:57 <acozine> yeah, maybe not a landing page
16:48:05 <samccann> #info would also be good if those 'other resources' links were more obvious. We knew there were subpages but not how to get to them until we fiddled a bit
16:48:16 <acozine> but somewhere, with a link for "What do we mean when we say 'Ansible'?"
16:49:27 <samccann> #info we may not need a full minimal landing page but something on the main page for 'what do we mean when we say Ansible'. Also remember people have the url docs.ansible.com memorized so many people will bypass any higher-level website page and come straight here.
16:50:09 <samccann> ok this has been good stuff.
16:50:14 <samccann> #topic Open Floor
16:50:25 <samccann> in case anyone had anything to talk about in the next few minutes?
16:52:10 <samccann> #info semantic markup is (mostly) here!
16:52:35 <samccann> sorry I dunno the full status. it's in antsibull-docs and a PR is ready and waiting to use that version on the docs build.
16:52:40 <acozine> I saw the PR got merged
16:52:43 <acozine> that's awesome!
16:52:55 <samccann> woot!
16:53:10 <samccann> and for those with website skills/opinions...
16:53:10 <samccann> #info add your thoughts to the static site generator for potential new website - https://github.com/ansible-community/community-topics/issues/210
16:53:38 <samccann> This is what will build a potential new website for the Ansible community (and these docsite pages will move into that build system etc)
16:54:07 <samccann> I think that's where we'll get some web design/ux help for sure including for these docs pages etc
16:54:55 <zbr> I think that I may have found a solution for my monorepo mkdocs building,...
16:56:25 <acozine> ssbarnea: cool!
16:56:54 <samccann> cool!
16:57:01 <samccann> meanwhile...
16:57:05 <samccann> #endmeeting