16:01:20 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:01:20 <zodbot> Meeting started Tue Nov  2 16:01:20 2021 UTC.
16:01:20 <zodbot> This meeting is logged and archived in a public location.
16:01:20 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:01:20 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:20 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:01:40 <samccann> #topic opening chatter
16:01:45 <samccann> who's around to talk the docs today?
16:02:13 <ariordan> \o/
16:02:23 <samccann> #chair ariordan
16:02:23 <zodbot> Current chairs: ariordan samccann
16:03:18 <samccann> andersson007_ dericcrago dmsimard  tadeboro briantist cyberpear felixfontein mrproper[m] Xaroth you folks chatting docs today?
16:04:16 <ariordan> It seems quiet today.
16:04:22 <samccann> lol yep
16:04:46 <samccann> We can talk to each other for a bit!
16:05:00 <ariordan> 😀
16:05:04 <samccann> Agenda is https://github.com/ansible/community/issues/579#issuecomment-953192227
16:05:19 <samccann> oh forgot acozine if you are around to talk docs!
16:05:39 <samccann> I wonder if my ping is off
16:06:12 <samccann> dmsimard: deric.crago Felix Fontein
16:06:19 <samccann> there's some matrix pings if it helps
16:06:32 <samccann> meanwhile
16:06:37 <samccann> #topic Action Item review
16:07:27 <samccann> #info opened PR to change the meeting time but not merged yet https://github.com/ansible/community/pull/634
16:08:08 <ariordan> Does it need any further changes, or will I merge it?
16:08:20 <samccann> if you have merge rights, go for it!
16:09:07 <samccann> I also got the room reminder working and 🤞the cyb-clock 15 min reminders
16:09:15 <samccann> Any other action items to discuss?
16:09:17 <ariordan> Yay!
16:09:42 <ariordan> No other action items, I think.
16:10:37 <samccann> Cool. We're on track for  the core-2.12 release from the docs perspective. I'll have a few WIP PRs we won't merge until just before the release( because they'd show up on devel right away)
16:10:41 <ariordan> I merged the meeting time PR.
16:11:34 <samccann> yay!  thanks!
16:12:12 <ariordan> I can't see the preview in the expand/collapse test PR any more, but it looked good when I could see it. https://github.com/ansible/ansible/pull/75695
16:12:38 * acozine waves
16:12:41 <samccann> yeah any time we publish to the test site, it risks overwriting some older thing
16:12:44 <acozine> sorry i'm late
16:12:51 <samccann> I'll get back to it once core releases
16:12:53 <samccann> #chair acozine
16:12:53 <zodbot> Current chairs: acozine ariordan samccann
16:12:55 <samccann> Welcome!
16:13:00 <acozine> I remembered the changed time this morning, then forgot again
16:13:10 <ariordan> Hi, acozine
16:13:11 <samccann> heh
16:14:01 <ariordan> I was thinking about checking out the expand / collapse PR and testing it on the file that acozine mentioned in a comment.
16:14:47 <acozine> I'd be really interested in seeing that on the testing site
16:15:01 <remindbot[m]> @room cyb-clock chimes - 15 minutes have past
16:15:03 <ariordan> It has huge codeblocks.
16:15:10 <samccann> ooo the chime works!
16:15:40 <ariordan> 🔔
16:15:41 <acozine> yeah, and the page goes on below and has a bunch of interesting material that i think folks often miss
16:15:43 <samccann> ariordan: did you want to pull down the PR and add that to it? I'm happy if you wanna commit that change back in if it works!
16:15:57 <ariordan> I'll do that.
16:16:07 <samccann> I just picked a random example to prove it out
16:16:44 <acozine> yeah, I'm sure it was easier to test on something a bit smaller at first
16:17:09 <ariordan> #action ariordan to check out https://github.com/ansible/ansible/pull/75695 and test it on https://docs.ansible.com/ansible/latest/user_guide/playbooks_vars_facts.html
16:17:22 <samccann> cool thanks!
16:17:30 <samccann> Meanwhile we do have one non-agenda topic we can cover
16:17:42 <samccann> #topic M() and R() in module docs
16:18:28 <samccann> #info we removed mention of these in https://github.com/ansible/ansible/pull/74708 because they didn't work in options (see https://github.com/ansible/ansible/issues/73792 )
16:19:03 <samccann> This might have been overzealous on our part, but regardless, Felix Fontein feels he can get a fix in place for the options stuff soon(ish) so we can revert that PR soon.
16:19:10 <samccann> And since he's not here to defend himself...
16:19:25 <acozine> heh
16:19:35 <samccann> #action felixfontein to code up a fix for M() and R() on plugin options
16:19:57 <acozine> I'm impressed that we're closing the loop there, AND keeping the documentation accurate through the changes
16:19:57 <samccann> he did sort of agree the other day in the community channel, so now we'll have an action item to remember it by.
16:20:45 <samccann> well, purely by accident as someone mentioned M() and I said M() doesn't work anymore and felix said.. mostly it does except this corner case he could fix :-)
16:20:56 <samccann> but woot!
16:22:35 <ariordan> Will we need to update any docs afterwards?
16:22:57 <samccann> we will have to back out that PR yeah
16:23:20 <samccann> ok swinging to a wide topic
16:23:28 <samccann> # topic updates on ongoing work
16:23:32 <samccann> oh fun. not sure what I did there
16:23:39 <samccann> #topic updates on ongoing work
16:23:44 <acozine> hey
16:23:55 <samccann> i went all big n bold for a bit!
16:23:56 <acozine> I meant, heh
16:24:14 <samccann> #info not much activity on the list of ongoing work
16:24:31 <samccann> I wonder if we want to prioritize that list? or if there is higher priority stuff we should tackle next?
16:24:57 <samccann> i'm good at making lists... less good at setting a priority on 'em.
16:25:28 <samccann> i think 'generating collection-level docs' is actually done, right?
16:25:31 <acozine> link?
16:25:46 <samccann> https://github.com/ansible/community/issues/579#issuecomment-953192227
16:26:02 <samccann> sorry it's in the agenda under  the action item review
16:26:22 <acozine> thanks
16:27:30 <samccann> I'd personally like to see briantist work on getting PRs to render docs in a collection working. Well, I think it's working, but ready for prime time so to speak?
16:27:36 <gwmngilfen-work> samccann: samccann: Element understand Markdown, you put #<space>topic
16:27:49 <samccann> # big n bold
16:27:57 <acozine> # header 1
16:28:01 <acozine> ## header 2
16:28:01 <samccann> tee hee! imma totally abuse that one, thanks Gwmngilfen
16:28:08 <acozine> erg, those look the same
16:28:11 <acozine> ### header 3
16:28:15 <samccann> ## header 2
16:28:20 <acozine> looks like a header is a header is a header
16:28:27 <samccann> AHAHA give writers some info and away they go!
16:28:29 <acozine> wonder how that looks on IRC though
16:28:33 <gwmngilfen-work> please do, especially in #social:ansible.com where the newsbot will store your markdown news updates for the Bullhorn :)
16:29:08 <gwmngilfen-work> acozine: it'll be plaintext, exactly as you wrote it, the original is sent to the bridge
16:29:28 <samccann> interesting on markdown going to the bullhorn!
16:29:39 <samccann> ok we digress
16:29:43 <gwmngilfen-work> we do :)
16:29:51 <samccann> meanwhile, anyone got a top thing they want to see docs doing next?
16:30:01 <samccann> anyone amongst us here anyway.
16:30:01 <remindbot[m]> @room cyb-clock chimes - 15 minutes have past
16:31:05 <acozine> I'd like to see more of the scenario guides move
16:31:17 <acozine> I suppose I could open a PR or two in that area
16:31:51 <acozine> what happened to our "list of top survey requests"?
16:31:54 <samccann> yeah we have an issue opened recently about one of them (azure maybe) being outdated. So.. moving them out
16:32:02 <samccann> oh good point!
16:32:13 <acozine> seems to me there were high-priority things there
16:32:20 <acozine> maybe they didn't make it into the DaWGs agenda
16:32:21 <samccann> #action samcann to add the top docs survey issues to the agenda
16:32:28 <samccann> good point!
16:33:29 <samccann> I'm also gathering possible docs-impacting features from core-2.13 here - https://github.com/ansible/ansible/projects/27
16:33:38 <samccann> in the 2.13 column :-)
16:34:39 <acozine> nice!
16:34:41 <samccann> i'm a bit stumped on how to move semantic markup forward. It's still a RH sort of thing where how do we coordinate this change across all the module doc output options, etc
16:35:41 <samccann> ok I think we might just open the floor early today.
16:35:42 <samccann> #topic Open Floor
16:35:43 <acozine> semantic markup will involve a large number of very large PRs
16:35:44 <samccann> This is your chance to bring up anything/everything docs related. Favorite PR/Issue, something else?
16:36:11 <acozine> nothing today from me
16:36:15 <samccann> Yeah oddly that feels like the easy part to me acozine. The hard part is getting overall buyin from all the pieces that spit out module/plugin docs
16:36:34 <samccann> mabye I'll open a Jira tix for it :-)
16:36:39 <acozine> heh
16:37:25 <samccann> anyone have anything else to discuss today?
16:37:47 <ariordan> I was wondering about the search improvements.
16:38:00 <ariordan> https://hackmd.io/UFlDKTE0Rn-R18UCGugmYQ
16:39:58 <acozine> have we gotten any feedback from users about whether including titles in searches made things better?
16:40:06 <samccann> it's not changed much since then ariordan . I did fix the weighting, but that's about it
16:40:27 <samccann> acozine: in general the few who looked said yes it was an improvement.
16:40:32 <acozine> that's cool
16:40:54 <acozine> maybe it's time to look at the last month or so of stats on "things users searched for and then left the site"
16:41:09 <samccann> We could
16:41:11 <ariordan> That sounds useful.
16:41:27 <samccann> we also need to play around and search for things to see what comes up
16:41:32 <acozine> and the reverse "things users searched for and then proceeded to a page and stayed there long enough that we guess they actually read something"
16:41:46 <acozine> maybe also compare stats from six months ago to now
16:41:47 <samccann> for example, somone in the user channel couldn't find the changelogs and search was useless. So it's a dual fix
16:42:13 <samccann> better title (no title says changelogs that actually links to the changelogs) and possibly a 'hack' in the search engine to make that new title come up first
16:42:15 <acozine> are we seeing more completed searches (or whatever the terminology is, I forget)
16:42:31 <samccann> I don't think the percentages changed much
16:42:37 <acozine> bummer
16:42:59 <acozine> the changelog seems like an easy one-off
16:43:12 <samccann> yep
16:43:19 <acozine> there's nothing else that should come up when someone searches for `changelog`
16:44:52 <samccann> I think what does come up is the how to do a changelog kind of stuff because that has a main title. The actual changelogs are listed on the release/maint page in a subheading in a table with no title.. that in my infinite noob wisdome called release notes
16:45:01 <remindbot[m]> @room cyb-clock chimes - 15 minutes have past
16:46:40 <acozine> ah
16:47:27 <acozine> well, that seems easy enough to update
16:47:40 <felixfontein> hi :)
16:47:47 <acozine> hey felixfontein
16:48:00 <samccann> hey felixfontein !
16:48:10 <samccann> #chair felixfontein
16:48:10 <zodbot> Current chairs: acozine ariordan felixfontein samccann
16:48:11 <felixfontein> there won't be a fix for R(), as that's impossible to fix without using RST. but fixing it for M() is possible (and easy)
16:49:02 <samccann> ok good to know
16:50:22 <samccann> so what are the scenarios where R() works and where it doesn't so we can update the docs accordingly?
16:51:30 <felixfontein> it doesn't work in the HTML blobs, i.e. in module/plugin/role arguments and return values
16:51:52 <felixfontein> though they will magically start working once we get rid of the HTML blobs (still my long-term plan :) ) and replace everything by 'pure' RST
16:52:00 <samccann> so it would only work in the notes?
16:52:11 <samccann> haha well there is that!
16:52:35 <samccann> but can RST handle the depth of those tables? (lookin at you bgp-anything modules)
16:52:39 <felixfontein> in the notes, in the main description, in seealso descriptions, in module/plugin (global) deprecation descriptions, ...
16:53:14 <samccann> #info R() works only in the notes, in the main description, in seealso descriptions, in module/plugin (global) deprecation descriptions
16:53:47 <samccann> and that's where M() works right now as well?
16:56:11 <samccann> ok we have 5 min left. Anything else we should discuss?
16:57:47 <acozine> we're probably not going to make progress on another topic in 3 minutes
16:58:00 <samccann> lol
16:58:11 <samccann> ok gonna end this with 2 min to spare!!
16:58:19 <samccann> #endmeeting