15:59:01 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:59:01 <zodbot> Meeting started Tue Feb 15 15:59:01 2022 UTC.
15:59:01 <zodbot> This meeting is logged and archived in a public location.
15:59:01 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:59:01 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:59:01 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:59:11 <samccann> #topic opening chatter
15:59:19 <samccann> @room Meeting time! Who is here to talk the docs?
15:59:31 <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:59:49 <briantist> o/
16:00:24 <samccann> andersson007_: tadeboro briantist  - you folks around to chat docs today?
16:01:29 <acozine> o/
16:01:42 <gwmngilfen-work> Ello
16:01:42 <samccann> #chair acozine
16:01:42 <zodbot> Current chairs: acozine samccann
16:01:55 <samccann> #chair briantist
16:01:55 <zodbot> Current chairs: acozine briantist samccann
16:02:11 <samccann> welcome welcome
16:02:21 <samccann> #chair Gwmngilfen
16:02:21 <zodbot> Current chairs: Gwmngilfen acozine briantist samccann
16:02:53 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1032834585
16:03:12 <samccann> #topic Documentation updates
16:03:37 <samccann> Gonna start with what feels like an appropriate topic since there is only 4 of us...
16:03:49 <samccann> #info looking for ways to expand this group and get more docs contributions. Ideas welcome!
16:04:02 <samccann> This may go hand in hand with..
16:04:10 <samccann> #info - should be be more async? How do we do async other than community-topics for things that need broad discussion?
16:04:58 <briantist> well I'm biased, but I think docs build will help contributors (and reviewers/maintainers), so they can see their stuff rendered, but I know that's largely waiting on me to make a little more production ready 😅
16:05:02 <acozine> is there a way to tell how many people are in this channel Gwmngilfen ?
16:05:14 <briantist> in IRC I see 38 members and 18 ops
16:05:41 <gwmngilfen-work> that depends on what you want. allegedy 127 accounts, but many will be IRC ghosts. but thats not active users
16:05:55 <samccann> yeah I'm thinking a couple of things -
16:06:01 <samccann> 1 - more actual docs contributions
16:06:12 <acozine> so we have 20 actual/potential community docs contributors here
16:06:15 <gwmngilfen-work> i have a library for getting stats on active talkers from the matrix side, let me update my cache ;)
16:06:38 <samccann> 2 - are we really getting 38 people here? There's probably about 5-7 max that pipe in regularly, and slowly there seems to be less that pipe in during these meetings.
16:07:14 <acozine> yeah, I figure folks who have joined the channel but don't generally speak up might be a good place to start
16:07:17 <briantist> some of the users in IRC are matrix doubles (`[m]` accounts and such)
16:07:26 <acozine> if they're here, they must have at least some interest in docs
16:07:41 <samccann> I've also had that time=zone revolving ping here for a couple of months and I don't think anyone has taken an easyfix item from the list.
16:08:08 <acozine> hm, that's weird, those easyfix issues used to get snapped up
16:08:23 <samccann> yes, we do get folks commenting during other times (not meeting times) so yep, some of that list are following and will pipe in when something attracts their attention
16:08:27 <gwmngilfen-work> briantist: [m] is a default suffix for a bridge user - so it's not a likely duplicate, just someone who hasn't set an IRC nick (and it's not required to do so)
16:08:53 <samccann> acozine: I suppose they may not be as easy as I think they are? but no one has pinged for help or desire to fix etc.
16:09:01 <samccann> and afaik they are regularly in the bullhorn too
16:09:43 <briantist> I meant specifically people whos how up as both (`user` and `user[m]`) which as far as my client knows are two different users
16:10:08 <acozine> well, the Bullhorn feels a bit more aimed at existing community contributors - collection maintainers and the like
16:11:14 <acozine> briantist: ah, yes, I've definitely seen those . . . a lot of people have a user in matrix and another in IRC, so that does skew the stats
16:12:11 <gwmngilfen-work> mean active users, last two weeks -> 7
16:12:17 <samccann> yeah that feels about right
16:12:27 <samccann> so i'm looking for ways we can bump that number up.
16:12:58 <samccann> Gwmngilfen: just for comparison, what's the mean active users on say the community or developer/user channels?
16:13:04 <samccann> (if that's easy to find).
16:13:42 <gwmngilfen-work> 21 for #community:ansible.com
16:13:55 <gwmngilfen-work> wait
16:13:58 <gwmngilfen-work> oh, darn
16:13:59 <samccann> one of the things I wonder is - who are the people we think might contribute more? Are the users who could viably want to clear up docs? (I see PRs like that a lot). Developers?
16:14:03 <gwmngilfen-work> there's a hole in the data
16:14:14 <samccann> data donuts for snack!
16:14:21 <gwmngilfen-work> ok, thast 2 weeks up to Feb 4th :P
16:14:23 <acozine> mmmm, donuts
16:14:32 <gwmngilfen-work> (for both satts)
16:15: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:15:02 <samccann> fwiw I've started inviting people to this chat whenever a merge a community PR
16:15:17 <gwmngilfen-work> organic growth ftw
16:15:23 <samccann> heh
16:15:59 <samccann> or perhaps I'm trying to 'measure growth' the wrong way? Maybe the organic growth should be measured in terms of # of docs PRs opened by non-RH people?
16:16:18 <samccann> like irc/matrix might not be for everyone...?
16:16:59 <acozine> +1 for inviting PR authors to the chat
16:17:06 <samccann> we did get a LOT more comments on docs-based communit-topic issues (like the changelog fragments) So async FTW for sure
16:17:30 <samccann> s/communit/community/
16:17:42 <acozine> and yeah, chat/IRC/Matrix isn't for everyone; participating on GitHub is awesome
16:20:13 <acozine> the more we can publicize the win-win nature of contributing to the docs (for newbies: you're learning git and GitHub, you're giving your hard-earned knowledge back to the community, etc., etc.), the better
16:20:38 <samccann> I did create some ROUGH videos on contributing to docs - https://studio.youtube.com/channel/UCPZR2EOHg9qHATqp8tVmptw/playlists
16:20:49 <acozine> ooooh, videos!
16:21:11 <samccann> And I think it was dmsimard who suggested a..erm..instruct tutorial that might helpo as well to show how easy peasy it can be?
16:21:27 <acozine> that sounds great
16:21:36 <gwmngilfen-work> Instruqt
16:21:43 <samccann> heh thanks
16:22:10 * acozine will BRB
16:22:16 <samccann> #action samccann to investigate an instruqt tutorial on contributing to docs
16:22:49 <samccann> ok probly enuf for that topic for now, thanks for brainstorming with me!
16:22:58 <samccann> #info - collection maintainers guide PR - https://docs.ansible.com/ansible/devel/index.html - hope to merge soon and then stub out the same content on community-docs repo.
16:23:34 <samccann> So same goal as I mentioned before - get the content from community-docs into ansible/ansible so we can publish all the info. Then go through with a BIG OL cleanup
16:24:03 <samccann> Basically, andersson007_ writes faster than I can keep up so need to move the stuff over fast so he's opening PRs against ansible/ansible instead :-)
16:24:17 <samccann> This brings me to another topic
16:24:36 <samccann> #topic Publishing non-versioned docs on a versioned docsite
16:25:06 <samccann> #info we have multiple pages on docs.ansible.com that are not tied to the core or Ansible release. Today, we publish them only to devel but this confused at least one person recently
16:25:20 <samccann> Devel has a lovely banner to say 'hey you might be in the wrong place' so to speak.
16:25:41 <acozine> which pages or sections are these?
16:25:44 <samccann> These community/contributor guides will be in the same boat
16:25:59 <samccann> Today we have I think the porting guides for sure and I think release/maint are only on devel
16:26:15 <samccann> on latest, they are stub pages that say 'go to devel'
16:26:33 <samccann> https://docs.ansible.com/ansible/latest/porting_guides/porting_guides.html
16:26:53 <acozine> ah, right
16:27:00 <acozine> what did the confused person say?
16:27:11 <acozine> what were they looking for? or what did they expect?
16:27:18 <samccann> they are following the search results for say porting guide and get a stub page on latest to go to devel. They go to devel and the banner says' user beware this is not guaranteed stable.
16:27:25 <acozine> heh
16:27:39 <acozine> fair enough
16:28:12 <samccann> so the journey itself was a problem. "click here, then click there, then get a worrisome banner". I'll try to find the issue where this is documented later but that's the gist of it
16:28:51 <samccann> #info we did this devel-only publishing because PRs weren't being backported so latest frequently had stale info, and most of these are not version-specific anyway
16:29:29 <acozine> we also put the porting guides on devel because otherwise you don't capture all available versions/jumps
16:29:30 <samccann> so part of this was to solve the backport problem due to lack of people to maintain all the backporting etc.
16:30: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:30:03 <samccann> yeah. And something like community guides have no release, but today, we have only the option to publish with a version
16:30:13 <samccann> aka the problem just gets bigger
16:31:26 <samccann> we could probably split them off to an unversioned url, but then we hit that nasty search/findability problem - if it's not on docs.ansible.com/ansible, the embedded search today can't find it. and readers may not even be aware it exists (which would mean less contributors!)
16:31:45 <acozine> yeah, i's a conundrum
16:31:57 <samccann> hello rock!  Hey hardplace!  Feeling the squeeze? Why yes I am!
16:32:14 <acozine> heh
16:32:25 <samccann> ok so back to the general question - should we publish community guides only to devel and stub them out on latest?
16:32:42 <samccann> or is this more a community-topic discussion?
16:32:56 <acozine> maybe so . . .
16:33:12 <acozine> I don't see much harm in including them on versioned docs going forward
16:33:29 <samccann> the harm is they get stale
16:33:34 <acozine> true
16:33:36 <samccann> no one is doing the backports
16:34:02 <acozine> I guess it depends what the rate of change is
16:34:08 <samccann> I can mention that in the community-topic. Maybe someone has a clever way of doing autobackports if the label is applied?
16:34:26 <samccann> well Andrei is writing a LOT. So it's still a changing set of docs for sure
16:34:44 <samccann> I'll open a community-topic and see what folks think
16:34:51 <acozine> sounds great
16:35:20 <samccann> #action samccann to open community-topic to debate community guides on devel only or regular backports to latest etc
16:35:33 <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
16:35:40 <samccann> ^^ for the meeting minutes ;-)
16:35:47 <samccann> #topic Doctools updates
16:35:57 <samccann> #info adding extra links to collection and module docs pages - https://github.com/ansible-community/antsibull/pull/355
16:36:16 <samccann> Thanks to felix for ^^ and Gwmngilfen .  Comments welcome.
16:36:56 <samccann> I think this one puts buttons up to make opening issues on a collection easier (aka a replacement for the missing edit on github functionality we used to have)...and then some.
16:37:37 <acozine> oh, cool!
16:37:45 <samccann> #info to see this in action - https://ansible.fontein.de/collections/community/dns/
16:37:59 <samccann> more examples in the PR but it's cool for sure!
16:38:41 <samccann> another one from felix - #info Improve attributes table PR - https://github.com/ansible-community/antsibull/pull/401 looks good!
16:38:49 <samccann> #info Improve attributes table PR - https://github.com/ansible-community/antsibull/pull/401 looks good!
16:38:56 <samccann> (to make the info work)
16:39:17 <acozine> I'm looking at these and I see the note about `Edit on GitHub` only being available on the module
16:39:20 <samccann> That one makes the new attributes table look and work like the parameters table. Cool stuff!
16:40:16 * acozine needs to read these properly
16:40:16 <samccann> you havea link to what you are seeing?
16:41:11 <acozine> in pull 355 it says `The very first version only has a "Edit on GitHub" link on the module and plugin, but hey, that's the very first step :-)` but when I open the example links, I don't see it, at least, not in the usual spot
16:41:18 <acozine> https://github.com/ansible-community/antsibull/pull/355
16:41:22 <samccann> ok yeah
16:41:38 <acozine> but I've only given it a quick glance
16:41:57 <samccann> What I'm seeing also is that there is nothing on the module page that says 'go to collection level breadcrumb to open an issue'
16:42:00 <acozine> I'll dig around a bit this week - this looks like a fantastic improvement
16:42:07 <samccann> But let's both put comments on the PR itself
16:42:31 <acozine> yeah
16:43:20 <samccann> okay we have time for...
16:43:26 <samccann> #topic open Floor
16:43:50 <samccann> Those who have lasted this long - here's the time to bring up anything docs related? Favorite issue/pr? some other docs topic?
16:44:30 <acozine> what's the overall count this week?
16:44:45 <acozine> open docs PRs, open docs issues in the core repo?
16:44:59 <samccann> all docs prs are in core repo at this point
16:45:00 <acozine> hmm, that's something we could try
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:16 <samccann> 71 open prs, 24 docs-only
16:45:16 <acozine> well, there might be some in individual collections too
16:45:46 <samccann> yeah I don't track those at all.
16:45:57 <samccann> 123 docs issues
16:46:01 <samccann> (in core)
16:46:02 <acozine> the "something we could try" is to post "shoutouts" in chat to community contributors who do submit PRs, or even comments
16:46:27 <acozine> to make more of a connection between the GitHub repo and the chat channel
16:47:08 <acozine> of course, not everyone uses the same nick here as on GH, and not everyone even has a login for IRC/Matrix, but it might be worth a try
16:47:29 <acozine> for PRs that don't make it onto the agenda
16:47:44 <acozine> just a little visibility for folks
16:48:04 <samccann> worth a try when I can connect a github person to a chat person, yep
16:48:45 <acozine> maybe even if we can't   - it's as much for other people to see as for the contributor tosee
16:48:48 <acozine> s/tosee/to see/
16:49:27 <samccann> ok I'll give it a try
16:50:00 <samccann> i wonder if a section in the bullhorn is worth it? just announce the names of contributors to merged docs PRs?
16:50:13 <samccann> 'thanks foo, bar, and tiddly for the docs contributions this week!"
16:50:32 <acozine> the advantage of chat over the Bullhorn is that people can 'chat back'
16:50:41 <acozine> the Bullhorn is read-only
16:50:44 <acozine> chat is read-write
16:50:46 <bcoca> i would expand to 'contributors' in general, probalby top 10 (that are not paid to do this, lik eme)
16:51:15 <bcoca> ^ if bullhorn, chat, depends on channel
16:51:27 <acozine> bcoca: I feel like we already recognize Top Ten types, it's more the first-timers I'd give shout-outs to
16:51:27 <samccann> bcoca: yeah but I can't sign up to maintain that list every week!  but I like the idea of thanking contributors in general
16:51:53 <bcoca> can have 2, top 10 + new people
16:52:02 <acozine> sure
16:52:12 <bcoca> list can be automated generation, just need 'criteria'
16:52:26 <acozine> we're looking to encourage folks to join, get started
16:52:46 <acozine> for most new folks, making the Top Ten is a big mountain to climb
16:53:31 <acozine> but if folks join the chat and see shoutouts for "first PR merged" and maybe a link so they can see how easy it is, then maybe they'll feel like contributing is within their capabilities
16:53:56 <acozine> which it absolutely is!
16:54:04 <bcoca> i dont disagree, but think that both are possibel (was unaware we already did top 10)
16:54:05 * acozine climbs down off her soapbox
16:54:12 <samccann> heh
16:54:36 <samccann> #action samccann to followup with community team on best ways to give shout outs to new contributors and those in top 10 so to speak
16:54:42 <samccann> great ideas!
16:55:07 <bcoca> also we have 'tons' of projects now ... all in need of general/docs PRs
16:55:14 <acozine> bcoca: well, we don't officially recognize a Top Ten Contributors list, but my bet is if we did, it would be the same folks who already participate in meetings and who get `@`'ed a lot in chat today
16:55:38 <acozine> anyway, yeah, we could do both
16:55:54 <bcoca> fyi, https://github.com/ansible/ansible/pull/74963 is getting close to landing, so i expect a ton of 'docs' activity getting filters and tests documented
16:56:45 <acozine> awesome
16:56:59 <acozine> speaking of big mountains to climb . . . congrats bcoca
16:57:33 <acozine> that was a ton of work and has been a long time coming
16:57:43 <samccann> woot!!
16:57:44 <bcoca> been planned since 2.4 ....
16:58:10 <samccann> so this basically allows someone to come in now and document those filters and tests? (once it merges)
16:58:14 <bcoca> and this pr only has about 10% of core documented, will have to make many followups
16:58:21 <bcoca> yep
16:58:40 <bcoca> https://github.com/ansible-collections/community.general/pull/4203 <= example documenting filter that is in 'multifilter file'
16:58:56 <bcoca> https://github.com/ansible-collections/community.general <= example documenting filter that is in single file
16:59:12 <bcoca> https://github.com/ansible-collections/community.general/pull/4202 sorr, that one
16:59:23 <samccann> @bcoca does your PR have docs as well on how to use this? :-)
16:59:42 <acozine> sorry to skip out on this discussion, but I have another meeting at the top of the hour
16:59:48 <acozine> thanks folks!
16:59:52 <bcoca> samccann: not yet, but for the 2nd case, its just the same as for other plugins, the '.yml' files are the 'new feature
16:59:56 <acozine> #unchair acozine
16:59:56 <zodbot> Current chairs: Gwmngilfen briantist samccann
17:00:02 * acozine waves
17:01:09 <samccann> yeah we'd need docs for when/where to use the yml files and formatting example etc
17:01:26 <samccann> but we are getting late in this meeting.  Thanks everyone!
17:01:43 <samccann> one last pause in case anyone wants to bring up a final topic before we end the meeting?
17:03:00 <samccann> #endmeeting