15:01:40 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:40 <zodbot> Meeting started Tue Jun  7 15:01:40 2022 UTC.
15:01:40 <zodbot> This meeting is logged and archived in a public location.
15:01:40 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:40 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:40 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:57 <samccann> #topic opening chatter
15:02:05 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:12 <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:25 <briantist> o/
15:02:28 <briantist> half here as usual
15:02:50 <orandon[m]> hi samccann about to do a demo so won't be around for the first bit
15:02:59 <samccann> #chair briantist
15:02:59 <zodbot> Current chairs: briantist samccann
15:03:07 * tremble is lucking as usual.
15:03:08 <samccann> #chair Don Naro
15:03:08 <zodbot> Current chairs: Don Naro briantist samccann
15:03:12 <samccann> cuz I won't remember later
15:03:16 <tremble> lurking even
15:03:29 <samccann> #chair tremble
15:03:29 <zodbot> Current chairs: Don Naro briantist samccann tremble
15:03:32 <samccann> for lucky lurking!
15:04:02 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1142330915
15:04:24 <samccann> though we always welcome topics that aren't on the agenda.
15:04:34 <acozine> o/
15:04:42 <samccann> #chair acozine
15:04:42 <zodbot> Current chairs: Don Naro acozine briantist samccann tremble
15:04:45 <samccann> welcome everyone
15:04:54 <samccann> #topic Documentation updates
15:05:28 <samccann> #info revamped getting started published! - https://docs.ansible.com/ansible/devel/getting_started/index.html
15:05:38 <felixfontein> sorry I won't be around for most of today's meeting
15:05:50 <samccann> thanks to dnaro, whom I won't ping cuz he's got a demo going on somewheres in the ether
15:05:54 <acozine> we'll miss you felixfontein
15:06:03 <samccann> ok thanks for popping in to let us know!
15:06:39 <samccann> There's a topic we'll discuss later but I'll probably open a community-topic on it for async fun
15:06:41 <acozine> full disclosure, I'm being distracted by chainsaws and the reflection of folks in bright yellow shirts out my office window - we are having 3 trees taken down today
15:08:00 <samccann> now that's a lot of noise!
15:08:28 <acozine> yes, it is
15:08:29 <samccann> Ok so part of the getting started revamp is it has moved locations and the quickstart video was outdated so that's not  there anymore either as a separate page
15:08:55 <acozine> wow, I thought that video would never go away
15:09:06 <samccann> heh it does when you remove it!
15:09:15 <acozine> it's nice to see some succession planning and pruning going on!
15:09:28 <samccann> there may be a better one? dunno. we'll search but it doesn't need it's own page if we do find one.
15:09:36 <samccann> Anyway, that means ... fun time... REDIRECTS!
15:09:40 <acozine> oof
15:09:55 <samccann> Sadly, I can't post the PR because the docsite repo is private (still dunno why...).
15:10:38 <samccann> #info need some reviews on these http redirects for  the old getting started and quickstart guide pages - https://pastebin.com/iYCskNLD
15:10:46 <samccann> So I copied the diffs to pastebin ^^
15:11:09 <samccann> It's on the test site - http://docs.testing.ansible.com/ansible/devel/index.html
15:11:39 <samccann> though that's not much help unless you hack the url to the old page. the diffs cover both devel and latest
15:11:58 <samccann> but latest won't have the new getting started guide til Ansible 6 releases, so that part won't work til then...
15:12:23 <samccann> so won't merge the underlying PR until Ansible 6 release day. But if anyone sees issues with the pastebin, do let me know.
15:12:41 <samccann> before it goes published and the interwebs let me know :=)
15:12:43 <acozine> ah, getting started is a new directory
15:13:27 <samccann> Yep. dnaro is taking a 'fresh look' at these things. So i'm hoping we can really get better structure there (along with redirects as needed). This one seemed easy.
15:13:59 <samccann> speaking of redirects, I'm going to 'info' this question for felix and others who aren't here.
15:15:08 <samccann> #info we have a set of redirects 2.9 <-> Ansible 3,4,5,(6). Do we need them around for Ansible 7 when 2.9 has already EOL'd?
15:15:09 <acozine> Hm, I get a 404 on the test site
15:15:11 <acozine> here: http://docs.testing.ansible.com/ansible/devel/user_guide/intro_getting_started.html
15:15:39 <acozine> the URL without the `/user_guide/` part redirects to that one ^^^
15:15:49 <acozine> but that one doesn't redirect to the new index page yet
15:16:01 <acozine> or maybe there's another redirect somewhere that's overriding it?
15:16:04 <samccann> hmm that should have worked
15:16:08 <acozine> yeha
15:16:10 <acozine> * yeah
15:16:28 <acozine> that's why I'm wondering if there are multiple redirects for that same URL
15:17:30 <samccann> this is the only existing redirect:
15:17:31 <samccann> RedirectMatch permanent "^/ansible/(devel|latest)/intro_getting_started.html" "/ansible/$1/user_guide/intro_getting_started.html"
15:18:03 <acozine> yeah, I think you need to remove that one
15:18:11 <samccann> i did
15:18:16 <acozine> ah
15:18:23 <acozine> then I have no idea why it isn't doing the right thing
15:18:24 <samccann> see here - https://pastebin.com/iYCskNLD
15:18:54 <samccann> it's hard to see but the - is removing it, and the two + should be replacing it with the new site
15:18:55 <acozine> d'oh, I missed the `-` and `+` signs
15:19:14 <samccann> DAGNAMMIT!
15:19:29 <samccann> let me restage my PR. maybe something overwrote it
15:19:49 <acozine> ah, that could be, yeah
15:20:17 <samccann> yeah looking at jenkins, there were 3 rebuilds last night, triggered by commits
15:20:27 <samccann> luckily this is a quick one... gimme a few secs
15:20:57 <acozine> oh, good - at least that's a reasonable explanation
15:21:21 <samccann> ok I think it works now. try again?
15:22:24 <acozine> hm, i may need to clear my cache or wait a bit
15:22:58 <samccann> ok if anyone else is playing along at home, try this url - http://docs.testing.ansible.com/ansible/devel/user_guide/intro_getting_started.html
15:23:14 <samccann> it should redirect
15:23:19 <acozine> okay, that one does
15:23:48 <acozine> but this one doesn't: https://docs.ansible.com/ansible/devel/intro_getting_started.html
15:23:50 <samccann> and this one should - http://docs.testing.ansible.com/ansible/devel/intro_getting_started.html
15:24:01 <acozine> or rather, it does, to the 404
15:24:04 <acozine> I think the order might matter
15:24:08 <samccann> yeah not a clue what that page is.
15:24:35 <acozine> it was the pre-2.5 equivalent page
15:24:48 <acozine> back when all the docs were in a single big directory
15:24:58 <samccann> yeah that's the full set of redirects we had to remove to get Ansible the package redirect working
15:25:04 <acozine> then in 2.5 we created the User Guide and the Getting STarted page moved there
15:25:21 <samccann> aka we can't have redirects pre 2.5 and Ansible package docs at the same time.
15:25:40 <acozine> I think it's possible
15:25:41 <samccann> there is an issue opened for that, but I dunno how to fix it.
15:25:53 <acozine> I know I ran into this before
15:25:55 <samccann> it wasn't possible back when we removed it specifically because we couldn't get stuff working.
15:26:01 <acozine> ah, okay, then I'm mis-remembering
15:26:03 <samccann> back when you were here. Lemme dig up the PR for it
15:26:16 <samccann> ya know, could be I'm misremembering it! redirects scare me
15:26:40 <acozine> if it's pre-2.5 or post-2.5, and we can't have both, I'd vote for keeping post-2.5
15:27:40 <acozine> I would expect a chain of redirects to do the right thing if they are in the correct order, but again, it's been a while since I last wrestled with this
15:28:29 <acozine> one possible option would be to update the 404 page itself, maybe put in a footer with the most popular pages or something?
15:28:35 <acozine> if the redirects don't/won't work
15:28:41 <samccann> ok I found the PR that removed it, but of course it's a private repo (GRRR)
15:29:18 <samccann> This is what the descripton says  - Comments out the most general redirect from the really old docs, which has been blocking our attempts to publish new docs for Ansible 3.0.0 as /ansible/3/*.html.
15:29:35 <samccann> and this is what was removed
15:29:37 <samccann> RedirectMatch permanent "^/ansible/(?!latest|devel|\d\.+)(.+)?.html" "/ansible/latest/$1.html"
15:30:15 <samccann> Now, Ansible 3 is long since EOL. So I could try putting it back in place and see if it really was just a 3/x problem
15:30:45 <samccann> but my guess is it has something to do with the 2.9 <---> Ansible 3/4/5/6 redirects.
15:30:49 <samccann> so it may be a case of:
15:31:46 <samccann> 1 - cannot have redirects for  pre 2.5  (what we have now)
15:31:48 <samccann> 2 - Can have redirects for pre-2.5 but cannot have redirects for 2.9 <--> Everything Ansible Package.
15:32:25 <samccann> Since 2.9 doesn't exist anymore in the version switcher, option 2 might actually be the preference. I seem to recall that was the driving reason for all those  other redirects?
15:32:54 <acozine> that sounds comprehensive
15:32:55 <samccann> ok I'll test it out and if that seems the case, I'll open a community-topic to see if we have agreement on which set of redirects loses out :-)
15:33:49 <samccann> #action samccann -  test out bringing back redirects for pre -2.5 (https://github.com/ansible/docsite/pull/38/files) and if  that works, open community-topic to discuss if we bring that back but lose redirects 2.9 <--> Ansible package docs
15:34:18 <samccann> #info Seems like our redirects are either pre-2.5, or 2.9 <--> Ansible package (to support version switcher)
15:34:34 <samccann> #info but 2.9 is EOL and no longer in version switcher so may not need those redirects anymore.
15:34:47 <samccann> phew. Okay thanks for walking through that with me!
15:35:22 <samccann> ok gonna move on
15:35:29 <samccann> #topic Ansible community-writers
15:35:55 <samccann> #info we now have a batch of technical writers volunteering to help out with Ansible docs (across all projects)
15:36:08 <acozine> Hooray!
15:36:28 <samccann> #info for now, this is limited to docs PR reviews and anything well-described in the issue that can be solved with Github Edit button.
15:37:05 <samccann> aka - they aren't ansible experts so need to know exactly what to change in a docs issue. Also of varying degrees of git experience, so limiting to the Edit on Github capability so they don't need to branch etc.
15:37:28 <samccann> We've had 30-40 PR reviews, and a handful of issues closed thanks to these folks!
15:38:01 <samccann> It's not overnight turnaround on a request, but  there are enough of them now that I can't keep up with feeding them stuff to do!
15:38:12 <acozine> heh, that's a great problem to have!
15:38:15 <samccann> #info this is open to collection owners, any ansible-related project that needs help
15:38:16 <samccann> indeed!
15:38:28 <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:39:13 <samccann> #info always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
15:39:18 <samccann> the usual plug ^^ ;-)
15:39:57 <samccann> #topic doctools
15:40:10 <samccann> #info Do we want to add names to changlogs? See https://github.com/ansible/awx/releases/tag/21.1.0 (especially new contributors)
15:41:01 <samccann> So i really REALLY liked when I saw the AWX release notes, that they had a new contributors section. I'd love to see us to at least that much. But having the name of the person who added a changelog item seems a nice to have as well.
15:41:29 <samccann> To share credit etc etc. I'm wondering if it's something `antsibull-changelog` could do?
15:41:48 <samccann> felixfontein isn't here today to answer, but I figured I'd ask folks what they  think of the idea overall.
15:42:34 <samccann> we can't do it the way AWX does it afaik because they use github releases and ansible/ansible doesn't. And I'm guessing ansible the package doesn't either?
15:43:05 <acozine> ooh, that's a cool idea
15:43:21 <acozine> something to bring up in the community meeting as well?
15:44:00 <samccann> yeah definitely. But thinking maybe as a community-topic to get async feedback on the idea.
15:44:04 <acozine> sounds like a good idea
15:44:15 <samccann> it may not even be technically possible. I just linked 'release notes' to 'change logs' in my head and thought felix could work some magic ;-)
15:45:20 <acozine> it seems like something we can do - we pull in the commit message, right? so why not the committer as well?
15:46:28 <samccann> well the changelogs are specific fragments that the PR owner writes. But yeah, the name info must be there for those. I don't know about new modules etc since that's not a hand-crafted changelog fragment. And what happens if the person creating the changelog fragment is not the person who created the feature so to speak. Sometimes people forget.
15:47:08 <samccann> I know ansible/ansible detects new contributors with a label. Dunno about any of the collections in Ansible (package) though.
15:48:01 <acozine> Mmm, yeah, there are so many levels with collections
15:50:34 <samccann> yeah. Just thinking a collection owner from a big company might actually have the changelogs written by a techwriter for example. It's a corner case, but could easily give credit to a batch of features to the writer ;-)
15:50:49 <acozine> and that's a BAD thing???
15:51:02 <samccann> HAHA writers control the WORLD!
15:51:16 <acozine> I'm joking, it would be good to credit the person who wrote the code as well
15:51:43 <samccann> yeah. Maybe I'll bring it up in the community meeting tomorrow for some chatter first before opening a topic on it
15:51:48 <acozine> but my bet is that if we implement it, folks will figure out how to get their "names in print" so to speak
15:52:11 <samccann> yeah my guess is 90% or more are the developer writing the changelog fragments.
15:52:30 <acozine> based on some of the changelog fragments we see . . . that's likely
15:52:38 <samccann> ooo snap!
15:52:59 <samccann> but yeah, they are the quick notes on what changed.
15:53:08 <acozine> they are mostly written from a coder's point of view, rarely from a user point of view
15:53:21 <acozine> still useful, of course
15:53:45 <samccann> hmm I should check our guidelines.  I wonder if we mention it should be written for a user in most cases, unless the change specifically impacts a developer.
15:54:54 <samccann> nope, we don't!
15:55:20 <samccann> #action samccann to create issue to add to changelog fragment instructions that they should be written for end users unless the change is specific to a developer
15:55:29 <samccann> ok wow time flies.
15:55:31 <samccann> #topic Open Floor
15:55:39 <samccann> Anyone having anything they want to discuss today about docs?
15:56:10 <acozine> Newcomers welcome, all questions encouraged
15:58:30 <samccann> ok last call for docs stuffs/ideas/questions before we end the meeting... (tho this channel is always open for docs stuffs/ideas/questions outside meeting time!)
15:59:29 <samccann> ok then!
15:59:33 <samccann> #endmeeting