16:00:59 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:00:59 <zodbot> Meeting started Tue Nov 22 16:00:59 2022 UTC.
16:00:59 <zodbot> This meeting is logged and archived in a public location.
16:00:59 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:00:59 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:00:59 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:01:05 <samccann> @room Meeting time! Who is here to talk the docs?
16:01:09 <oranod> hello hello
16:01:11 <oranod> o/
16:01:18 <samccann> #chair Don Naro
16:01:18 <zodbot> Current chairs: Don Naro samccann
16:01:27 <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:01:37 <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:01:52 <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:27 <samccann> felixfontein: briantist around to talk docs today?
16:03:38 <samccann> Official agenda is https://github.com/ansible/community/issues/643#issuecomment-1307505913
16:03:51 <Amara8469[m]> How can I join
16:04:04 <briantist> I'm barely here, will be very distracted
16:04:15 <briantist> Amara8469[m]: just type this `o/` (raising your hand)
16:04:43 <samccann> #chair briantist Amara#8469
16:04:43 <zodbot> Current chairs: Amara#8469 Don Naro briantist samccann
16:05:02 <samccann> Welcome Amara#8469 ! Yes all you have to do is say something and we'll add you to the chairs. Glad to have you today!
16:05:12 <samccann> Official agenda is https://github.com/ansible/community/issues/643#issuecomment-1307505913
16:05:32 <oranod> yes welcome Amara#8469
16:05:47 <samccann> #topic Action Item updates:
16:06:04 <felixfontein> o/
16:06:19 <samccann> Basically I'm still struggling with getting remindbot here to put out the 1 hr notification of this meeting.  I think that's the only open action item this week.
16:06:25 <Amara8469[m]> Alright !
16:06:25 <samccann> #chair felixfontein
16:06:25 <zodbot> Current chairs: Amara#8469 Don Naro briantist felixfontein samccann
16:07:19 <samccann> #topic Documentation updates
16:07:54 <samccann> Looks like Ansible 7 release is 'in the works' So Don Naro will be starting the docs release process. He's got all the PRs queued up and waiting
16:08:26 <samccann> Don Naro: - there's a good chance the release won't happen until crazy-o'clock for you. I can get things published etc if that happens.
16:08:46 <oranod> sounds good, thanks
16:08:53 <oranod> fingers crossed on all those redirects
16:09:02 <samccann> it's also possible it won't happen until crazy-oclock for me, in which case docs don't show up until tomorrow ;-)
16:09:48 <samccann> Yeah so we have a new batch of redirects for Ansible 7 for  the user guide restructuring. Testing those now, but if we hit a snag, Don added stub pages so people will know what moved where.
16:10:35 <samccann> So to clarify that a bit better. When we move rst files around, we like to use HTTP redirects on the server so readers don't have to do extra clicks to find the page they were looking for. And to avoid the dreaded '404
16:11:14 <samccann> . The user guide was one BIG OL guide. Don Naro split it into multiple smaller guides. Much easier to find things I think.
16:11:28 <samccann> And the joy of ansible, if anyone doesn't like it, I'm sure we'll hear about it!
16:11:32 <samccann> :-)
16:13:03 <oranod> in fairness I think we've been pretty vocal about the user guide restructure
16:13:18 <samccann> yep. we broacast that move pretty widely.
16:13:22 <samccann> broadcast even
16:13:31 <oranod> brocast
16:13:35 <samccann> HEH
16:14:08 <oranod> I do hope we get some positive feedback and all the changes ultimately result in a better experience
16:14:45 <samccann> I think it will, but change always comes with a bit of resistance. That said, this is a vast improvement imo and we'll have redirects etc.
16:15:02 <samccann> #info Archived 2.4 docs. Will set up redirects next week.
16:15:38 <samccann> So continuing our effort to move very old end-of-life docs to a separate location, 2.4 is there now. I didn't want to slap up redirects this week since it's a short week for those of us in the US
16:15:59 <samccann> but the following week, all old 2.4 bookmarks will be redirected to the latest documentation.
16:16:35 <samccann> we didn't hear anything when we did this with 2.3, so ..all's good!
16:16:49 <samccann> The goal is to go up to 2.8. But we need to decide a couple of things
16:17:06 <samccann> 1 - do we do this for Ansible releaes (3,4,5,etc)?
16:17:43 <samccann> From the search perspective (the reason we started this effort), we get minimal website hits on those releases because we always used just 'latest' or 'devel'. VERY VERY few people are using the number in the url.
16:18:08 <samccann> so we don't HAVE to archive. But do we WANT to archive so we have a full list of links for anyone using something old?
16:18:15 <felixfontein> I think it's ok to also do this for 2.10, 3, 4, 5, ...
16:18:50 <felixfontein> about whether we WANT an archive, that's a very good question. I think it's good to have an archive, but it shouldn't be there forever.
16:19:03 <felixfontein> now the big question is: how many years are enough? :)
16:20:49 <samccann> well see, when last we talked about this (we meaning me and who even remembers who else, but I'll blame that bcoca guy)
16:21:01 <bcoca> guilty!!!
16:21:05 <samccann> it was brought up that ansible stays on pypi forever. All releases.
16:21:07 <samccann> heh
16:21:38 <samccann> So we've followed suit on the docs with that.
16:21:59 <bcoca> iirc the archive was driven by product to make google search less 'sticky' on old versions
16:22:11 <felixfontein> I think pypi is a different story than docsites
16:22:41 <samccann> yeah that's the reason for the archive. But once we have archived the ones causing google to have a bad hair day, do we continue for consistency
16:23:11 <samccann> felixfontein: yeah that's a point I don't have a lot of experience with. I know enterprise/product documentation tends to stay around for YEARS
16:24:28 <samccann> but that is usually because of compliance/support contracts etc
16:24:35 <felixfontein> how about keeping docsites in the archive for 5 years, and move all EOL docs to the archive?
16:25:03 <felixfontein> I guess it's also because of storage is cheap, and regularly deleting old versions costs more than just keeping them ;)
16:25:08 <samccann> that might be a good compromise.
16:25:25 <samccann> yeah to be honest, I haven't a clue HOW to delete the docs
16:25:36 <samccann> I'm sure there's a way, but I haven't stumbled on it yet
16:26:17 <felixfontein> `rm -rf`? :)
16:26:34 <samccann> heh
16:27:14 <samccann> ok one last wrinkle - do we archive RIGHT AWAY on EOL day, or wait say 6 months?
16:27:38 <samccann> So using Ansible 6 as an example - archive it in a month, or wait until Ansible 8 comes out and archive it then?
16:27:39 <felixfontein> waiting a certain amount of time sounds sensible
16:28:23 <felixfontein> one month sounds a bit short, 6 months sounds ok, something inbetween is probably also ok.
16:29:04 <samccann> The one gotcha is creating all those redirects, but what's another 100 or so compared to what we already have, eh?
16:29:56 <samccann> aka there may be a point of 'diminishing returns' here. But we'll see as we get the really old stuff archived and redirected, how hard do those redirects get.
16:31:17 <samccann> We could always put up an archive for 6 that actually just uses the existing url (https://docs.ansible.com/ansible/6/index.html)
16:31:24 <felixfontein> maybe at some point we should remove the rediects
16:31:52 <samccann> Since none of the Ansible (package) urls are causing  search problems. That would give us a full archive w/ all the redirect fuss
16:32:14 <samccann> felixfontein: the screams I got when we removed ONE ANCIENT redirect from like ansible 2.1 docs or something
16:32:30 <samccann> to the point the poster had to be censured for violating the CoC.
16:33:41 <samccann> at some point, we hope to make this repo public. Which will be great, cuz then we can get community help with the redirect mess we have there today
16:34:36 * bcoca suspects there is a redirect to 12th level of hell hidden in there
16:35:04 <samccann> heh yeah probably
16:35:17 <samccann> #chair bcoca
16:35:17 <zodbot> Current chairs: Amara#8469 Don Naro bcoca briantist felixfontein samccann
16:35:24 <samccann> #topic What's next?
16:35:35 <samccann> Looking for thoughts on where we should target docs improvements next?
16:35:35 <samccann> https://github.com/ansible-community/community-topics/issues/81 to add your ideas.
16:36:03 <samccann> So two things that came up - Accessibility, and revamping the docsite a bit based on 'personas'. Those will likely be a big focus in the next few months
16:36:30 <samccann> personas being the fancypants term for 'what sort of readers do we have coming to the docs and how can we make it easier for them to find what they are looking for
16:38:13 <samccann> once I get some pencil-scratches down on community personas, I'll pop things up for discussion etc.
16:38:28 <samccann> #topic doctools
16:38:40 <samccann> #info we can do minor updates to antsibull-docs in devel and stable-2.14 w/o updating the CI containers if we are okay with that drift.
16:39:19 <samccann> So ansible 7 docs will be build with antsibull-docs 1.7.3 for example, but the CI containers in ansible/ansible are usiing 1.7.1 in  that stable branch
16:39:47 <felixfontein> you mean patch updates, or minor updates?
16:39:51 <samccann> I'll also start testing out updated requirements for all the dependencies (but for devel only).
16:40:04 <samccann> patch I guess. 1.7.x
16:40:16 <samccann> #undo
16:40:16 <zodbot> Removing item from minutes: INFO by samccann at 16:38:40 : we can do minor updates to antsibull-docs in devel and stable-2.14 w/o updating the CI containers if we are okay with that drift.
16:40:32 <samccann> #info we can do patch updates to antsibull-docs in devel and stable-2.14 w/o updating the CI containers if we are okay with that drift.
16:40:35 <samccann> there we go!
16:40:57 <felixfontein> :)
16:40:59 <samccann> do we have other items to talk about in the docstools area? The stuff that builds the docs
16:41:08 <samccann> builds and publishes :-)
16:42:18 <felixfontein> I don't think so...
16:42:47 <felixfontein> (at least not from my side :) )
16:43:01 <samccann> ok cool
16:43:05 <samccann> #topic Open Floor
16:43:16 <samccann> Anything anyone would like to bring up related to docs ?
16:44:43 <samccann> as a reminder, I'll be out after tomorrow for the annual American OverEatiing day (aka Thanksgiving)
16:44:55 <oranod> should we maybe talk about those personas a little more or is it too soon?
16:45:01 <samccann> Don will be here for any messes I make before I head out :-)
16:45:16 <oranod> ha, although I do have plans for some turkey myself
16:45:22 <samccann> Don Naro: yeah hoping to kickstart that conversation next week
16:45:53 <oranod> sure, was just thinking it might be something to dig into a little now
16:46:57 <samccann> well we have a few minutes left so I can share current ideas
16:48:10 <samccann> right now, i'm thinking we have readers in a few buckets - content creators (people writing playbooks and such) content developers (people writing python etc code - including collection developers), and non-coding contributors (writers, meetup people etc etc)
16:48:50 <samccann> and then we have the fuzzy I don't0really-know AWX/GalaxyNG admins.
16:49:10 <samccann> But that brings up the goal to include all of the Ansible projects, even if we don't currently host their docs on docs.ansible.com
16:49:34 <oranod> yeah
16:51:25 <samccann> there is one other vague, not sure it's real, persona - content consumer
16:51:41 <samccann> aka someone who runs someone else's playbooks etc (doesn't write a playbook themselves).
16:52:12 <samccann> I feel like maybe AWX has people like that but I'm not sure. I struggle with that persona in terms of what do they need to know  etc
16:52:22 <oranod> wouldn't that persona be more like a galaxy NG user?
16:52:49 <samccann> Well a galaxy ng user down'loads collections yes, but afaik very few collections today include prebuilt playbooks.
16:53:28 <samccann> I got the feeling AWX might have more people who are just using stuff there (I think they are jobs in AWX??). gundalow might be able  to clarify that one for us when he has the chance
16:55:21 <oranod> sigh. there are so many parts of ansible I have yet to learn.
16:55:29 <samccann> oh same here!
16:55:59 <oranod> I wonder if we could do a bit of polling or survey as part of the persona identification or is that a bit too overkill really?
16:56:16 <samccann> I think we will, but I'd like to get some discussions  going first.
16:56:41 <samccann> then eventually we can put up a document for feedback and a github community topic etc
16:56:55 <samccann> and make sure we ping people from all of the ansible projects
16:58:11 <oranod> sounds like a good plan. it'll be exciting to go through all that and make docs.ansible.com even better.
16:58:52 <samccann> woot woot!
16:59:37 <samccann> ok we are at the  top of the hour. Any last item before we end the meeting today?
17:00:27 <samccann> #endmeeting