16:00:18 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:00:18 <zodbot> Meeting started Tue Dec 14 16:00:18 2021 UTC.
16:00:18 <zodbot> This meeting is logged and archived in a public location.
16:00:18 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:00:18 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:00:18 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:00:19 <samccann> #topic opening chatter
16:00:19 <samccann> @room Meeting time! Who is here to talk the docs?
16:00:28 <gwmngilfen-work> ish
16:00:36 <acozine> o/
16:01:06 <samccann> #chair acozine Gwmngilfen
16:01:06 <zodbot> Current chairs: Gwmngilfen acozine samccann
16:01:48 <samccann> we have a loads to talk about... as usual :-)
16:02:10 <samccann> #info Agenda - https://github.com/ansible/community/issues/579#issuecomment-988107597
16:03:04 <samccann> #topic Documentation work
16:03:26 <acozine> I've still got a branch going for the "when should i consider using a role" docs
16:03:34 <samccann> #info we are frontloading the agenda now to highlight documentation work (vs the docs tooling that we've focused on a lot in the past)
16:03:51 <samccann> Great acozine ! looking forward to seeing that
16:04:07 <samccann> I don't know that we have any other docs action items lurking, do we?
16:04:58 <acozine> I don't know of any . . . do we want to talk about the `disambiguation` issue?
16:05:00 <samccann> I know we have docs-tooling action items we can go over later
16:05:01 <acozine> or is that more docs tooling than docs?
16:05:18 <samccann> yeah if it's tooling, let's wait a few to finish docs (words on paper) stuff first
16:05:27 <acozine> sure
16:05:40 <samccann> #info docs issues if anyone is looking to help https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs
16:06:04 <samccann> #info and docs easyfix issues for that quick sense of accomplisment - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs+label%3Aeasyfix
16:06:32 <samccann> one new thing that came to mind
16:06:48 <samccann> #info Do we need a list of new collections 'somewhere' in the porting guide?
16:07:15 <samccann> I noticed this before. I think it's in the changelog but actually looking at our Ansible porting guide, I can't tell when a batch of new collections come in for a release
16:07:16 <acozine> could be useful
16:07:43 <acozine> the porting guide could link to the repo for making decisions on collection-inclusion
16:07:49 <acozine> can't remember what that's called ATM
16:08:08 <samccann> There is this - https://github.com/ansible-community/ansible-build-data/blob/main/5/CHANGELOG-v5.rst#id216
16:08:20 <acozine> but it might inspire people to look there and to encourage maintainers who are on the cusp of getting their collections in
16:08:40 <samccann> (in the changelog). It doesn't list just new, it lists all, but you can tell what is new because it has no entry in the Ansible 4 column :-)
16:08:49 <acozine> heh
16:08:54 <acozine> that's pretty obscure
16:09:07 <samccann> #info the full list of collections is in the changelog https://github.com/ansible-community/ansible-build-data/blob/main/5/CHANGELOG-v5.rst#id216
16:09:29 <acozine> here's the issue I was thinking of:
16:09:30 <acozine> https://github.com/ansible-community/community-topics/issues/32
16:09:38 <acozine> that's for Ansible 5
16:09:38 <samccann> Yeah so I'm thinking we can either list new collections directly at the top of the porting guide (with some coding magic)
16:09:56 <samccann> yeah not sure that is user focused, which the porting guide is. That's more developer focused
16:10:36 <samccann> my nickel guess is a collection owner looking to be included isn't looking in the porting guide for that info (which isn't  to say we don't need to make it more obvious somewhere else)
16:11:19 <samccann> I guess my conundrum - do we add the list to the porting guide, or change the text around the changelog link there to say 'see the full list of included collections in the changelog)
16:11:20 <samccann> s/)/'/
16:11:29 <acozine> I meant more that users might look at the candidates under review and say "this would be very useful to me" or similar
16:11:58 <acozine> but your two options sound good
16:12:29 <acozine> I'd vote for changing the text of the existing link
16:12:39 <acozine> the porting guides are already pretty long
16:12:43 <samccann> ok I'll open an antsibull issue to see if there is a quick/easy way to add the new collections list.
16:13:00 <samccann> Well it's only like 5 collections or less each release it seems to me.
16:13:03 <acozine> but if we could find a way to pull just the new collections, that wouldn't add too much
16:13:03 <acozine> yeah
16:13:26 <samccann> yeah totally - just the new ones. If that's not doable, we can just change the wording to say see the changelog for full list of collections
16:13:35 <acozine> changing the text of the changelog link is still also a good idea
16:13:51 <acozine> to let users know that there is a full list of collections there
16:14:14 <samccann> #action samccann to open an antsibull issue to see if we can list just new collections at top of porting guide. If not, change wording for changelog link to say see it for full list of collections
16:14:16 <samccann> yep
16:14:55 <samccann> Meanwhile on docs - brian has been busy creating docs for filter/test plugins - https://github.com/ansible/ansible/pull/74963
16:15:00 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:15:18 <samccann> It's still early times, but figured I'd highlight it if anyone wants to go take a look
16:15:29 <samccann> #info filter/test plugins docs WIP - https://github.com/ansible/ansible/pull/74963
16:17:02 <samccann> #info split controller from 2.12 still needs docs. There is some starter info here - https://github.com/ansible-collections/overview/issues/45#issuecomment-923507542 that might help if anyone is up for starting this
16:18:16 <samccann> one last docs thing that comes to mind
16:18:40 <samccann> #info call for help - Please look at the docs PR backlog and comment/review/approve any you can - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs_only
16:19:20 <samccann> Anything else regarding documentation before we move to docs-tooling fun?
16:20:22 <samccann> okeydoke
16:20:30 <acozine> nothing comes to mind
16:20:34 <samccann> #topic Docs-tooling
16:21:06 <samccann> Gwmngilfen: - you had an action time to 'n finalizing linking metadata for collections and turning it into a proposal'
16:21:27 <samccann> any progress there? I know there's a PR already, but wasn't sure if that particular piece is done
16:21:30 <gwmngilfen-work> i think felix has beaten me to it, given he's already written an implementation
16:21:44 <samccann> haha yep
16:22:09 <acozine> damn the proposals, full steam ahead!
16:22:31 <samccann> #info PR to implement the extra links  -https://github.com/ansible-community/antsibull/pull/355  and how they look now - https://ansible.fontein.de/collections/community/dns/
16:22:52 <gwmngilfen-work> i had a brief review of the gist and it's sane enough. I haven't had time to really think if it needs any more special fields like the edit_on_github section does, but I think it's enough to get started (as demonstrated)
16:23:10 <gwmngilfen-work> it should be ok to iterate on this as it doesn't impact other systems
16:23:35 <samccann> yep
16:24:29 <acozine> Those look pretty good
16:24:36 <samccann> #info still iterating on removing html blobs from plugin docs. Latest PR -https://github.com/ansible-community/antsibull/pull/360 to allow us to turn this on/off for memory hogging problems
16:24:56 <samccann> (oof sorry... jumped a head a bit... keep going on the links)
16:24:58 <acozine> it's a little weird to be reading hte documentation and have a `Documentation` link
16:25:05 <gwmngilfen-work> yeah, this moved a lot faster than I anticipated. much thanks to felxi for the work done
16:25:27 <gwmngilfen-work> acozine: true, that one might be redundant :P
16:25:34 <acozine> what is the Homepage?
16:25:34 <gwmngilfen-work> (it does link back to itself)
16:25:42 <samccann> heh
16:25:46 <gwmngilfen-work> appears to be github for this example
16:25:52 <acozine> Homepage and Repository seem redundant
16:25:58 <acozine> er, duplicative
16:26:08 <acozine> they both point to the same page
16:26:09 <samccann> well some collections DO have separate docsites. I wonder if there is a way to tell and only put up an 'other documentation' button or something
16:26:18 <gwmngilfen-work> that may not always be the case though. i think the point is that we can render whatever a maintainer needs
16:26:57 <samccann> Well, we may need to balance all options with  what's the most common set of options we want to display
16:27:15 <gwmngilfen-work> whether we want to is different, but I think the code just uses each element in extra_links to display a button name and target
16:28:04 <gwmngilfen-work> https://github.com/ansible-community/antsibull/pull/355/files#diff-0b507052df25c0ce3272bb29884026abfc668b8d64c61184b539e78154c7a031R35-R37 seems to be the relevant bit, from a quick skim
16:28:59 <acozine> yeah, it does work, and I'd be okay with it as a start
16:29:01 <gwmngilfen-work> i would probably agree that we might want to limit the list of available buttons - mainly because it's our docs, and I don't want someone putting up a button labelled "Ansible Sucks" ...
16:29:07 <acozine> heh
16:29:15 <acozine> I hadn't even thought of that possibility
16:29:27 <gwmngilfen-work> but as a PoC it's ace, now we just need to haggle :)
16:29:38 <acozine> but yeah, it seems like we could pick the most useful ones
16:29:41 <gwmngilfen-work> tbh that should be caught as part of the collection review, but still
16:30:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:30:03 <samccann> i'm looking at where we added email addresses for authors. I'm not sure that's a good idea
16:30:25 <samccann> feels like we open them up for spam by doing that. Where are we getting that info?
16:30:28 <acozine> I think those are straight out of the GitHub repo, so they're already "out in the wild"
16:30:49 <gwmngilfen-work> even so, that should be opt in. but where are the emails? I nly see github IDs on the page...
16:31:19 <samccann> I still think there's a differenets between my github id being out there (and my email buried in there) and us publishing them in a docsite that gets 24 MILLION hits a year
16:31:33 <gwmngilfen-work> 💯
16:31:43 <samccann> https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_module.html#authors
16:31:44 <gwmngilfen-work> we dont have consent for that
16:32:33 <acozine> heh, Markus has a sense of humor about it, anyway, but yeah, we could suppress those
16:32:34 <gwmngilfen-work> is that part of this discussion though? or is that coming from somewhere else? I don't see the Homepage etc buttons on that page
16:32:55 <gwmngilfen-work> i mean, +100 for not scraping emails regardless of where it's happening
16:32:56 <samccann> it was a link from the same PR so I'm guessing it's included in the code somewheres
16:33:02 <acozine> I think it's https://github.com/ansible-community/antsibull/pull/355/files#diff-0b507052df25c0ce3272bb29884026abfc668b8d64c61184b539e78154c7a031R24-R25
16:33:04 <gwmngilfen-work> oh ok
16:33:25 <acozine> and the next section
16:34:27 <samccann> ok so please add your comments to the PR, esp as Felix couldn't make it today...so async away!!!
16:34:44 <gwmngilfen-work> :)
16:36:02 <samccann> #topic docs examples
16:36:12 <samccann> #info example repo is up for docs!  -https://github.com/ansible-community/community-examples/issues/2
16:36:19 <acozine> w00t!
16:36:24 <samccann> #info looking for a few good examples to seed it and get started
16:36:49 <samccann> I think the original proposal had some volunteers. I'll go dig back
16:36:50 <acozine> I remember there were some from the mailing list
16:38:23 <samccann> I don't want to jump on andersson007_ 's toes since he may already be spreading this request for examples around (or may just want a couple to start with).
16:38:26 <acozine> folks in Ansible User Help might also have contributions - I'd announce it there when it's ready
16:38:43 <gwmngilfen-work> good idea. should probably newsbot it too
16:38:55 <samccann> yeah just want to wait until he's ready
16:39:40 <samccann> #topic semantic markup
16:39:52 <samccann> #info starting with a formal proposal - https://hackmd.io/VjN60QSoRSSeRfvGmOH1lQ
16:39:58 <briantist> o/
16:40:00 <samccann> #info looking for feedback on that so we can finalize
16:40:10 <samccann> Welcome briantist !
16:40:18 <samccann> #chair briantist
16:40:18 <zodbot> Current chairs: Gwmngilfen acozine briantist samccann
16:40:29 <acozine> hey briantist
16:40:37 <briantist> sorry late, didn't get a ping this time :-/
16:41:06 <samccann> so on the semantic markup, it has gotten a bit more detailed/complex so we should take a good solid look -is the complexity worth it for the added links and optional CI validation etc.
16:41:14 <acozine> I looked at your test-update PR, but it's a bit outside my wheelhouse, so I didn't add a review
16:41:25 <samccann> aaaaa!!!
16:41:27 <samccann> the pings!
16:41:40 <acozine> ah, what's the new complexity on semantic markup?
16:41:41 <samccann> I did the at room ping, but that just pings matrix people, doh!!
16:41:44 <briantist> I kind of rely on the pings to let me know when meetings start
16:41:52 <briantist> ahhh
16:42:01 <samccann> sorry about that. I'll be sure to do a matrix ping and an irc ping
16:42:12 <briantist> thanks 🙏
16:42:14 <acozine> does the bot do both?
16:42:30 <acozine> if it doesn't, it should
16:42:32 <gwmngilfen-work> irc doesnt have a room ping, right?
16:42:47 <gwmngilfen-work> so you need to know who to ping, the bot cannot know that
16:42:57 <acozine> I thought `@here` or something did a room ping . . . no?
16:43:12 <gwmngilfen-work> pretty sure it does not, `@here` is Slack
16:43:34 <acozine> ah
16:43:36 <briantist> I don't think there's a room ping, seems like there's some set group of people that meeting organizers ping for various meetings
16:43:47 <acozine> ETOOMANYCHATPLATFORMS
16:43:56 <gwmngilfen-work> well you know my answer to that .... :)
16:44:03 <briantist> :(
16:44:07 <acozine> I used to just ping "folks who have joined us recently"
16:44:11 <acozine> it was pretty erratic
16:44:25 <gwmngilfen-work> right, there's no good solution on IRC, you have to guess
16:44:52 <gwmngilfen-work> (some would argue room pings are not a good soluton either, but thats another debate)
16:44:53 <samccann> yeah I have a list of the 'usual suspects' that I usually ping. I didn't this week but will next week along with the matrix room ping
16:45:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:45:41 <samccann> acozine: to answer your question - https://hackmd.io/VjN60QSoRSSeRfvGmOH1lQ#Markup-Specification
16:46:13 <samccann> shows a lot more complexity for the `O()` markup (and will be mirrored by `RV()` markup
16:46:31 <samccann> it brings the benefit of adding links and CI validation. But it is... more for developers to keep in mind to get it all right
16:47:53 <samccann> I mean I guess it's opt-in - like you use all that complexity if you are linking to a module suboption or sub sub option etc. So nice to have if you want to go that far, not required (but you won't get CI/linking if you don't)
16:49:14 <acozine> It still looks useful to me, but I'm generally a fan of standardization
16:50:05 <samccann> Yeah I want Felix to take a look at that spec, and then maybe we highlight it during the community talk, or get it in the bullhorn to get more eyes on it etc.
16:50:21 <acozine> that sounds great
16:50:41 <samccann> The goal is to finalize mostly what we in community want, and then get internal RH people looking at it for final approval or adjustments since it impacts many of their bits and bobs
16:51:41 <samccann> briantist: - did you have any updates on your work getting docs to render from within a collection PR?
16:52:20 <briantist> no updates really, it's working well in my collection, but I have a few other things to prioritize for now before I get back to trying to make that more generic
16:52:56 <briantist> with GitHub adding the ability to use other actions within composite actions, that's a nice path for splitting it up into a few custom actions people could use
16:53:07 <briantist> drawing the lines for those will be something to think about though
16:53:18 <acozine> actions within actions within actions, eh?
16:53:50 <acozine> it sounds like a great use of the latest GitHub capabilities
16:54:17 <briantist> yeah, before composite actions could only be built with run steps, so like shell scripts basically, now you can leverage other GH actions
16:54:22 <samccann> for sure
16:54:39 <briantist> and this process definitely uses other actions
16:55:41 <briantist> implementing it for other folks will have some complication no matter what because of the security implications, I've described that in an issue in my collection, but that's just something to learn about
16:55:59 <briantist> https://github.com/ansible-collections/community.hashi_vault/issues/138
16:57:27 <samccann> eep 2 minutes left!
16:57:28 <samccann> time for a quick
16:57:32 <samccann> #topic Open Floor
16:57:58 <samccann> here's the time where you can bring up anything docs related. Got an issue you want solved, a favorite PR waiting for review?
16:59:03 <acozine> after searching for something to post for user help I found this:
16:59:36 <acozine> there will be a short delay while I dig through my open tabs
16:59:42 <samccann> hahah
17:00:13 <samccann> ok meanwhile - I was considering using/abusing room nags and the reminder bot to post links to open docs issues and prs at different timezones
17:00:37 <samccann> Like once a day, post them here during US/AMEA times, and once a day at APAC times.  Helpful, or annoying?
17:00:39 <acozine> https://github.com/ansible/ansible/issues/75652
17:01:02 <acozine> looks like it could use more discussion / ideas
17:01:30 <acozine> samccann: I like the "daily docs issue" thing
17:01:39 <briantist> samccann: as someone who consistently has problems getting review for PRs, I'm in favor 😂 (though ironically that applies mostly to my non-docs PRs)
17:02:03 <samccann> hehe
17:02:06 <gwmngilfen-work> i would frown on using room pings too often. more than weekly feels intrusive
17:02:26 <acozine> maybe we could post without pings?
17:02:26 <gwmngilfen-work> that said, the docs room is your room, so go ahead :)
17:02:33 <samccann> ok so I could just make it a personal reminder. it would still show up here
17:02:42 <samccann> but without the annoying ping all
17:02:50 <acozine> if we announce it in the Bullhorn, it might motivate folks to look
17:02:54 <samccann> like the cybe-clock clone reminders
17:03:11 <acozine> yeah, those are great
17:03:13 <gwmngilfen-work> bullhorn will be moving to weekly sometime soon, so I can definitely see a space for raising a thing-of-the-week
17:03:26 <samccann> yeah there is a help wanted section in the bullhorn now (thanks cybette and Gwmngilfen ) I just have to fingure out how to use it
17:03:39 <acozine> I was thinking put "We're going to post docs issues daily in the channel" into the Bullhorn
17:03:47 <acozine> then put the actual isuses here
17:03:49 <acozine> issues
17:04:02 <acozine> but either/both would work
17:04:03 <samccann> #action - samccann to try a reminder bot on US and APAC times with links to open issues and prs (but no room bot nag)
17:04:31 <samccann> #action samccann to get easyfix docs issues into the newsbot
17:04:31 <acozine> if we could program it to post every 25 hours, that would step through all the TZs
17:04:41 <gwmngilfen-work> samccann: if that's not clear then I need to (a) show you and (b) document it better :)
17:05:02 <samccann> Gwmngilfen: I just havent looked yet how to do it
17:05:13 <acozine> yikes, i need to go
17:05:15 * samccann doesn't know where it's documented yet either
17:05:27 <acozine> thanks samccann for running the meeting!
17:05:39 <acozine> see you next week, or in between in the chat channel, folks!
17:05:44 <samccann> about time to wind up anyway
17:05:49 <acozine> #unchair acozine
17:05:49 <zodbot> Current chairs: Gwmngilfen briantist samccann
17:07:05 <samccann> #endmeeting