15:58:57 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:58:57 <zodbot> Meeting started Tue Jan 25 15:58:57 2022 UTC.
15:58:57 <zodbot> This meeting is logged and archived in a public location.
15:58:57 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:58:57 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:58:57 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:59:06 <samccann> #topic opening chatter
15:59:12 <samccann> @room ready to talk the docs?
15:59:14 <briantist> o/
15:59:49 <samccann> andersson007_ tadeboro cyberpear - around to talk the docs?
15:59:56 <samccann> #chair briantist
15:59:56 <zodbot> Current chairs: briantist samccann
15:59:57 <samccann> welcome!
16:00:01 * cyberpear half here
16:00:55 <samccann> #chair cyberpear
16:00:55 <zodbot> Current chairs: briantist cyberpear samccann
16:01:09 <samccann> or maybe we can make that a comfy cushion :-)
16:01:12 <gundalow> I'm on another meeting. I'll catchup later on.
16:01:23 <gundalow> s/on/in/
16:01:33 <samccann> ok thanks for letting us know!
16:01:43 <felixfontein> o/
16:01:49 <samccann> I'll start in with some minor updates
16:01:55 <samccann> #topic Documentation updates
16:02:13 <samccann> #info - start of splitting community guides - https://docs.ansible.com/ansible/devel/index.html
16:02:33 <samccann> That just separates the bits so it's easier to focus on a general community guide, a core contributor guide, and a collection contributor guide
16:03:23 <acozine> o/
16:03:28 <samccann> #info follow this topic to discuss this - https://github.com/ansible-community/community-topics/issues/60
16:03:38 <samccann> #chair acozine
16:03:38 <zodbot> Current chairs: acozine briantist cyberpear samccann
16:03:39 <samccann> Welcome!
16:04:33 * acozine reads the backscroll
16:04:48 <samccann> I need to clean up that topic and then widen the audience. We have still to discuss/decide if we move the collection contributor guide out of the ansible/ansible repo since it has nothing specifically to do with core.
16:05:05 <samccann> (moving source files only that is, it would still all be published to docs.ansible.com/ansible I think)
16:07:02 <samccann> one of the things we need to consider is the longer term vision - where do we envision Ansible docs say 2 years from now?
16:07:58 <samccann> If we say magically tossed in a better search engine, would it make sense to still keep all the guides the way we publish them ttoday? Would we want a navigation path on docs.ansible.com specific to contributors and developers, etc.
16:08:24 <samccann> We've talked a bit about that in the past but I think we have to take it more seriously now and open the discussion further etc.
16:08:44 <acozine> I think there's good value in having all the docs in a single site.
16:09:33 <samccann> yeah I appreciate quick thoughts here, but also we should put it in a community topic for discussion. Otherwise we each repeat ourselves every 6 months or so when these ideas float to the surface again.
16:09:47 <acozine> It supports people as they move "up the levels", from newcomer, to Ansible user, to community member, to contributor/WG member/maintainer
16:09:48 <gundalow> andersson007_: deric.crago ompragash dmsimard @dmsimard:matrix.org if you folks are around you may wish to join
16:10:02 <acozine> a single site lets people see what's possible
16:10:11 <gundalow> acozine: could you please clarify what you mean by "site"
16:10:34 <samccann> when you say single site acozine , you are not talking about docs.ansible.com as a single site, right? you are talking about docs.ansible.com/ansible?
16:10:46 <acozine> gundalow: by "single site" I mean docs.ansible.com/ansible
16:11:35 <acozine> content with a single internal search engine and a unified TOC (the existing one has a LOT of problems, but at least it's integrated)
16:11:50 <gundalow> Thanks
16:11:57 <samccann> #info supports people as they move "up the levels", from newcomer, to Ansible user, to community member, to contributor/WG member/maintainer with the way we have all on docs.ansible.com/ansible today
16:12:18 <samccann> #info with a single search engine and unified TOC
16:13:14 <samccann> That's what's kept us from making big changes before. I think a 'unified search' option is possible even if we split things into say docs.ansible.com/developer and docs.ansible.com/user
16:13:17 <acozine> that approach also leverages Ansible's traditional strength in search results
16:13:21 <samccann> but we wouldn't have the unified TOC
16:13:26 <acozine> external search results, I mean
16:13:53 <acozine> most searches for `Ansible foo` return results on docs.ansible.com/ansible
16:14:17 <acozine> information elsewhere doesn't get as many eyeballs
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:09 <samccann> yeah we'd need a search expert to help us out if we did move things to say docs.ansible.com/contributors or something. I think it's not an 'insurmountable' problem.
16:15:34 <samccann> But  the unified TOC is (insurmountable) if we move things around
16:16:08 <samccann> So I wonder how much that adds to the journey acozine talks about here that helps new users move and grow into eventual contributors, collection maintainers etc
16:16:18 <acozine> if there are serious advantages to splitting things up, we should consider those, of course
16:16:46 <acozine> but it would definitely dilute our audience
16:17:43 <samccann> yeah this is why I think I need to turn that into a separate community-topic. So we widen the audience and feedback etc. Otherwise it's just us three chickens pecking at the same kernels of corn  each time the topic comes up
16:18:38 <gundalow> Other things to consider, other projects will be coming online. Contributing to (say) AWX or Dev-tools doesn't have anything to do with ansible-core.
16:18:39 <samccann> anyone else following along, please do feel free to pipe in. this is an open discussion for sure
16:19:04 <samccann> #info another aspect of this - other projects will be coming online. Contributing to (say) AWX or Dev-tools doesn't have anything to do with ansible-core.
16:19:26 <gundalow> Really welcome thoughts from others that are lurking in the channel (yes you).
16:19:33 <samccann> heh
16:20:19 <samccann> #action samccann to start (or revamp) a hackmd to get some ideas down on separating the docsite up
16:20:32 <samccann> omgosh I practically had hand-tremors just typing that action item up LOL!
16:21:03 <samccann> but I think a hackmd is a good start. gets us talking but in a place where we can update/edit etc. And then once we have something midly coherent, turn it into a community-topic
16:22:20 <samccann> ok something hopefully less controversial...
16:22:23 <samccann> #topic changelog fragments
16:22:34 <samccann> #info please add your comments to https://github.com/ansible-community/community-topics/issues/64
16:22:57 <samccann> We are writing up some revised guidelines so developers have a good idea how to craft helpful changelog fragments.
16:24:21 <samccann> #chair felixfontein
16:24:21 <zodbot> Current chairs: acozine briantist cyberpear felixfontein samccann
16:24:41 <samccann> Sorry about that! scrolled back and realized you'd waved but I forgot to toss furniture at you!
16:25:18 * acozine watches the chairs flying through the air
16:25:28 <acozine> the changelog stuff will be great
16:25:43 <felixfontein> no problem :)
16:25:56 <samccann> yep. Exciting to get it down on paper so to speak. Should be helpful
16:26:17 <samccann> #topic examples repo
16:26:31 <samccann> #info we have the start of a repo of community-curated examples - https://github.com/ansible-community/community-examples
16:26:59 <samccann> I don't think andersson007_ is here to give us an update, but there are some examples and ideas popping up there so please spread the word!
16:29:15 <samccann> ok one final plug...
16:29:15 <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:29:26 <samccann> And we can move on to doctools
16:29:29 <samccann> #topic doctools
16:29:50 <samccann> any exciting updates felixfontein briantist ?
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:11 <briantist> in short: I don't have anything to update on docs build
16:30:24 <briantist> I'm fully on a new team at $DAYJOB as of the new year, so my weekdays are busy
16:30:42 <felixfontein> on the antsibull side, I'm waiting for a vote to finish, for a PR in the theme repo to be merged (and the result released), and for gwmngilfen-work to continue with the extra links proposal :)
16:30:51 <briantist> and this past weekend turned out to be less productive for OSS than I had imagined 😅
16:31:17 <acozine> briantist: did you change jobs?
16:31:24 <briantist> oh right I do need to put in a PR to antsibull also for sphinx-init, to determine which Ansible site intersphinx links should go to
16:31:32 <acozine> oh, new team at same employer
16:31:34 <briantist> acozine: no same company, new team
16:32:01 <samccann> :-)
16:32:09 <samccann> no worries. It's some amazing work ya got going there
16:32:18 <briantist> not that it's so relevant to the group, but the one thing I did create over the weekend was a new docsite page in `community.hashi_vault` if anyone would like to look :)
16:32:18 <briantist> https://github.com/ansible-collections/community.hashi_vault/pull/211
16:32:41 <briantist> thanks samccann, I still feel good about the docs build work and its future
16:34:01 <acozine> briantist: I've got that PR in an open tab for review
16:34:07 <briantist> thanks!
16:35:34 <samccann> ok looks like we might be short on topics today so time for...
16:35:42 <samccann> #topic Open Floor
16:36:23 <samccann> Here's the time to bring up anything on docs that's on your mind.
16:36:46 <samccann> got a PR or issue you want eyes on? Some feedback you want to give us? A docs conundrum or two?
16:37:14 <briantist> there was a lively discussion yesterday in the channel about validating docs or at least ensuring that collections don't break the docs build
16:37:53 <acozine> I haven't been actively looking, but I haven't seen any typo PRs in a while. Not sure if this means the docs are clean, or if we're not catching the typos, but given the volume we used to get, I'm hopeful that it means the docs are clean.
16:38:02 <acozine> briantist: what did folks suggest?
16:38:18 <acozine> when I run the full build, I see tons of warnings and errors in collections
16:38:37 <briantist> going to reiterate what I posted there, which is that the docs build will I think be a great tool for that; parts of the docs on using it will be examples on how to use it for only validation (if you don't want to do anything else with the build content), and that when the docs build matures and is more in use, I think we could consider making clean docs builds part of inclusion criteria (this is a ways out)
16:39:17 <samccann> The discussion came about in part because we post the error messages on the docsite when a collection plugin docs fails
16:39:38 <acozine> +100 for enforcing clean docs builds once we have tooling that helps maintainers fix errors
16:39:43 <samccann> But it's hard for a collection owner to 'validate' their docs. Like.. REALLY hard
16:40:11 <felixfontein> partially because some required tooling for that hasn't been merged to ansible-test
16:40:14 <acozine> yeah
16:40:27 <felixfontein> (though in the specific collection from yesterday it doesn't look like they actually run `ansible-test sanity`...)
16:42:04 <acozine> ah, well, that's a problem
16:42:17 <samccann> is it worth having an issue 'somewhere' that just tracks the other issues or PRs we need in place so that collection owners can verify their plugin docs before merging.. and we can 'eventually' make this a hard requirement?
16:42:24 <briantist> right, what I mean is that it is trivially easily using the docs build stuff to validate docs. Even if you aren't looking at them (typos/content), running it successfully proves they build.
16:42:48 <samccann> feels like a lot of different pieces need to click into place. I know I don't have 'em all in my head for sure
16:43:15 <briantist> it so that's the minimum possible use of it; anything more (showing changes on PRs, publishing) implicitly tests build too
16:43:49 <briantist> this would be part of the checks that run on push/PR so it would show up in PRs even if we're not adding the comment or showing differences (the build job would pass or fail)
16:44:46 <felixfontein> I think we also need a strict mode for antsibull itself, so that it will fail directly when some plugin docs cannot be converted to RST. that would be useful for CI.
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:06 <felixfontein> (for the real docs build it is important that it carries on and not fail :) )
16:45:32 <briantist> it's strict mode by default; I still have to add support in the build process for selecting the `--lenient` flag you told me about in antsibull ;)
16:46:04 <briantist> that's why it currently cannot build any collection with warnings, like c.g
16:46:07 <felixfontein> briantist: that's sphinx, not antsibull
16:46:15 <briantist> ah, ok
16:47:26 <felixfontein> apropos, a diversity docs PR: https://github.com/ansible/ansible/pull/76845
16:48:24 <samccann> I'm having weird time delays w/ my matrix client. I can't tell if the conversation has ended or I'm just in a long delay
16:48:51 <felixfontein> that happens from time to time with the irc<->matrix bridge apparently
16:49:02 <briantist> ah.. I hate when that happens, it usually negatively affects the IRC side, but yeah it's super annoying, especially during meetings
16:49:08 <acozine> felixfontein: thanks for pointing that one out
16:49:28 <acozine> I'm bummed we've missed those for so long
16:50:17 <samccann> thanks felixfontein !!
16:50:21 <felixfontein> acozine: there are some more occurences, but these are in code resp. module options and need deprecation etc.
16:50:38 <samccann> anything else before we close down the meeting for today?
16:51:17 <acozine> yeah, we can't unilaterally fix the code, but we should've caught the ones where the code has already been updated
16:51:45 <acozine> samccann: can't think of anything else, I'm still working on the "cheatsheet" PR
16:52:06 <acozine> which is, I think, my only open "to-do"
16:52:17 <samccann> ;-)
16:53:25 <samccann> ok hoping the relative silence isn't my delay but the natural end to the meeting
16:53:39 <samccann> since I say acozine's todo comment
16:53:47 <acozine> thanks samccann for running the meeting!
16:53:52 <briantist> thanks!
16:53:54 <samccann> /say/saw/
16:54:08 <acozine> and thanks everybody for all your work to make Ansible docs awesome(r)
16:54:15 <samccann> #endmeeting