15:58:57 #startmeeting Documentation Working Group aka DaWGs 15:58:57 Meeting started Tue Jan 25 15:58:57 2022 UTC. 15:58:57 This meeting is logged and archived in a public location. 15:58:57 The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 15:58:57 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:58:57 The meeting name has been set to 'documentation_working_group_aka_dawgs' 15:59:06 #topic opening chatter 15:59:12 @room ready to talk the docs? 15:59:14 o/ 15:59:49 andersson007_ tadeboro cyberpear - around to talk the docs? 15:59:56 #chair briantist 15:59:56 Current chairs: briantist samccann 15:59:57 welcome! 16:00:01 * cyberpear half here 16:00:55 #chair cyberpear 16:00:55 Current chairs: briantist cyberpear samccann 16:01:09 or maybe we can make that a comfy cushion :-) 16:01:12 I'm on another meeting. I'll catchup later on. 16:01:23 s/on/in/ 16:01:33 ok thanks for letting us know! 16:01:43 o/ 16:01:49 I'll start in with some minor updates 16:01:55 #topic Documentation updates 16:02:13 #info - start of splitting community guides - https://docs.ansible.com/ansible/devel/index.html 16:02:33 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 o/ 16:03:28 #info follow this topic to discuss this - https://github.com/ansible-community/community-topics/issues/60 16:03:38 #chair acozine 16:03:38 Current chairs: acozine briantist cyberpear samccann 16:03:39 Welcome! 16:04:33 * acozine reads the backscroll 16:04:48 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 (moving source files only that is, it would still all be published to docs.ansible.com/ansible I think) 16:07:02 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 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 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 I think there's good value in having all the docs in a single site. 16:09:33 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 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 andersson007_: deric.crago ompragash dmsimard @dmsimard:matrix.org if you folks are around you may wish to join 16:10:02 a single site lets people see what's possible 16:10:11 acozine: could you please clarify what you mean by "site" 16:10:34 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 gundalow: by "single site" I mean docs.ansible.com/ansible 16:11:35 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 Thanks 16:11:57 #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 #info with a single search engine and unified TOC 16:13:14 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 that approach also leverages Ansible's traditional strength in search results 16:13:21 but we wouldn't have the unified TOC 16:13:26 external search results, I mean 16:13:53 most searches for `Ansible foo` return results on docs.ansible.com/ansible 16:14:17 information elsewhere doesn't get as many eyeballs 16:15:01 @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 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 But the unified TOC is (insurmountable) if we move things around 16:16:08 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 if there are serious advantages to splitting things up, we should consider those, of course 16:16:46 but it would definitely dilute our audience 16:17:43 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 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 anyone else following along, please do feel free to pipe in. this is an open discussion for sure 16:19:04 #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 Really welcome thoughts from others that are lurking in the channel (yes you). 16:19:33 heh 16:20:19 #action samccann to start (or revamp) a hackmd to get some ideas down on separating the docsite up 16:20:32 omgosh I practically had hand-tremors just typing that action item up LOL! 16:21:03 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 ok something hopefully less controversial... 16:22:23 #topic changelog fragments 16:22:34 #info please add your comments to https://github.com/ansible-community/community-topics/issues/64 16:22:57 We are writing up some revised guidelines so developers have a good idea how to craft helpful changelog fragments. 16:24:21 #chair felixfontein 16:24:21 Current chairs: acozine briantist cyberpear felixfontein samccann 16:24:41 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 the changelog stuff will be great 16:25:43 no problem :) 16:25:56 yep. Exciting to get it down on paper so to speak. Should be helpful 16:26:17 #topic examples repo 16:26:31 #info we have the start of a repo of community-curated examples - https://github.com/ansible-community/community-examples 16:26:59 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 ok one final plug... 16:29:15 #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 And we can move on to doctools 16:29:29 #topic doctools 16:29:50 any exciting updates felixfontein briantist ? 16:30:01 @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 in short: I don't have anything to update on docs build 16:30:24 I'm fully on a new team at $DAYJOB as of the new year, so my weekdays are busy 16:30:42 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 and this past weekend turned out to be less productive for OSS than I had imagined 😅 16:31:17 briantist: did you change jobs? 16:31:24 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 oh, new team at same employer 16:31:34 acozine: no same company, new team 16:32:01 :-) 16:32:09 no worries. It's some amazing work ya got going there 16:32:18 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 https://github.com/ansible-collections/community.hashi_vault/pull/211 16:32:41 thanks samccann, I still feel good about the docs build work and its future 16:34:01 briantist: I've got that PR in an open tab for review 16:34:07 thanks! 16:35:34 ok looks like we might be short on topics today so time for... 16:35:42 #topic Open Floor 16:36:23 Here's the time to bring up anything on docs that's on your mind. 16:36:46 got a PR or issue you want eyes on? Some feedback you want to give us? A docs conundrum or two? 16:37:14 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 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 briantist: what did folks suggest? 16:38:18 when I run the full build, I see tons of warnings and errors in collections 16:38:37 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 The discussion came about in part because we post the error messages on the docsite when a collection plugin docs fails 16:39:38 +100 for enforcing clean docs builds once we have tooling that helps maintainers fix errors 16:39:43 But it's hard for a collection owner to 'validate' their docs. Like.. REALLY hard 16:40:11 partially because some required tooling for that hasn't been merged to ansible-test 16:40:14 yeah 16:40:27 (though in the specific collection from yesterday it doesn't look like they actually run `ansible-test sanity`...) 16:42:04 ah, well, that's a problem 16:42:17 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 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 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 it so that's the minimum possible use of it; anything more (showing changes on PRs, publishing) implicitly tests build too 16:43:49 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 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 @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 (for the real docs build it is important that it carries on and not fail :) ) 16:45:32 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 that's why it currently cannot build any collection with warnings, like c.g 16:46:07 briantist: that's sphinx, not antsibull 16:46:15 ah, ok 16:47:26 apropos, a diversity docs PR: https://github.com/ansible/ansible/pull/76845 16:48:24 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 that happens from time to time with the irc<->matrix bridge apparently 16:49:02 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 felixfontein: thanks for pointing that one out 16:49:28 I'm bummed we've missed those for so long 16:50:17 thanks felixfontein !! 16:50:21 acozine: there are some more occurences, but these are in code resp. module options and need deprecation etc. 16:50:38 anything else before we close down the meeting for today? 16:51:17 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 samccann: can't think of anything else, I'm still working on the "cheatsheet" PR 16:52:06 which is, I think, my only open "to-do" 16:52:17 ;-) 16:53:25 ok hoping the relative silence isn't my delay but the natural end to the meeting 16:53:39 since I say acozine's todo comment 16:53:47 thanks samccann for running the meeting! 16:53:52 thanks! 16:53:54 /say/saw/ 16:54:08 and thanks everybody for all your work to make Ansible docs awesome(r) 16:54:15 #endmeeting