2025-03-25 16:16:21 <@orandon:ansible.im> !startmeeting DaWGs (Documentation Working Group) 2025-03-25 16:16:22 <@ansibot:ansible.im> Meeting started at 2025-03-25 16:16:21 UTC 2025-03-25 16:16:23 <@ansibot:ansible.im> The Meeting name is 'DaWGs (Documentation Working Group)' 2025-03-25 16:16:35 <@x1101:matrix.org> There's _also_ the possibility that the bot is just haunted. 2025-03-25 16:16:36 <@orandon:ansible.im> @room who's around to talk the docs today? 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! General run of the meeting - We go over action items, give docs updates… maybe have a topic or two, and go over doctooling updates (all the fun stuff behind the scenes that get us docs.ansible.com!) official agenda at https://forum.ansible.com/t/documentation-working-group-agenda/153/7 2025-03-25 16:16:52 <@x1101:matrix.org> o/ 2025-03-25 16:16:52 <@orandon:ansible.im> oh... that's fun. a haunted bot. 2025-03-25 16:16:58 <@orandon:ansible.im> o/ obvs 2025-03-25 16:17:18 <@orandon:ansible.im> yeah I see that there was an end meeting last week but it must not have taken effect for whatever reason 2025-03-25 16:17:56 <@orandon:ansible.im> !triage 2025-03-25 16:18:49 <@orandon:ansible.im> let's try that again 2025-03-25 16:18:54 <@orandon:ansible.im> !topic Triage 2025-03-25 16:19:02 <@orandon:ansible.im> ^link https://github.com/ansible/ansible-documentation/issues/2463 2025-03-25 16:19:26 <@orandon:ansible.im> here's one of my favourites! one sentence per line. 2025-03-25 16:21:06 <@orandon:ansible.im> I've added a comment in that issue with some thoughts and am generally in favour of one sentence per line but I'm not sure how we'd enforce that and it's a big job to retrospectively apply it. 2025-03-25 16:21:22 <@orandon:ansible.im> maybe somewhere in the contributor guide we could add a recommendation, if we haven't already done that.... 2025-03-25 16:24:50 <@orandon:ansible.im> hmmm. maybe it's worth adding an entry to the docs style guide about this. 2025-03-25 16:24:55 <@orandon:ansible.im> ^link https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html 2025-03-25 16:26:41 <@orandon:ansible.im> ^link https://github.com/ansible/ansible-documentation/issues/2462 2025-03-25 16:28:11 <@samccann:ansible.im> o/ 2025-03-25 16:28:17 <@samccann:ansible.im> strollin in late 2025-03-25 16:28:29 <@orandon:ansible.im> aloha samccann 2025-03-25 16:28:52 <@acozine:ansible.im> One sentence per line seems like a reasonable standard. Though we might have a very large number of PRs if we're going to implement it across all our documentation. 2025-03-25 16:29:02 <@acozine:ansible.im> Or one absolutely gigantic PR. 2025-03-25 16:29:11 <@orandon:ansible.im> thanks Kristian Heljas I think applying that guideline retrospectively might be problematic 2025-03-25 16:29:17 <@x1101:matrix.org> or even a medium number of medium sized PRs 2025-03-25 16:30:29 <@orandon:ansible.im> my feeling is that we should recommend it as a best practice and encourage it's use during review. starting with a recommendation in the style guide might be a good starting point. over time we could shift things towards wider adoption. 2025-03-25 16:31:10 <@x1101:matrix.org> set it as a standard, and fix things as they're touched for other reasons until we hit a critical mass of things ? 2025-03-25 16:32:19 <@samccann:ansible.im> what is the recommendation for PRs that don't do this? Are we going to bug people to switch their changes? Keeping in mind a number of our PRs come from github edits 2025-03-25 16:32:31 <@samccann:ansible.im> or for those of us with commit rights, do we just force in the change? 2025-03-25 16:33:55 <@orandon:ansible.im> I'd be easy about it and recommend it as a best practice, especially for new content, but not try to force it. I know some people will probably have their own opinions and preferences. 2025-03-25 16:34:32 <@samccann:ansible.im> true confessions ;-) 2025-03-25 16:34:47 <@samccann:ansible.im> tho I'm happy to edit my cruft... will just take me time to adapt 2025-03-25 16:34:55 <@orandon:ansible.im> I can take an action to send a PR and update the style guide. I can ping folks here for review or talk about it at the next DaWGs 2025-03-25 16:35:04 <@samccann:ansible.im> sounds good 2025-03-25 16:37:14 <@orandon:ansible.im> for that 2nd issue in the triage, I feel like that's right up bcoca's alley. it's a valid point about being explicit about the behaviour but I know there are a few internal twists and turns with priority and where Ansible looks for things. so my feeling is that we should probably try to get some draft wording together and ping bcoca on the issue. 2025-03-25 16:37:19 <@orandon:ansible.im> does that sound reasonable? 2025-03-25 16:38:09 <@x1101:matrix.org> yeah. and its def a thing that could use more explicit clarity. I know I've struggled with it even 2025-03-25 16:38:14 <@samccann:ansible.im> makes sense to me yeah 2025-03-25 16:38:48 <@orandon:ansible.im> !topic scheduled jobs for RTD publishing 2025-03-25 16:38:58 <@orandon:ansible.im> Lyle (He/Him) (@x1101): this one is for you 2025-03-25 16:39:24 <@orandon:ansible.im> two issues related to this 2025-03-25 16:39:28 <@orandon:ansible.im> ^link https://github.com/ansible/ansible-documentation/issues/2049 2025-03-25 16:39:40 <@orandon:ansible.im> ^link https://github.com/ansible/ansible-documentation/issues/2050 2025-03-25 16:40:40 <@x1101:matrix.org> I remember looking at these in the fall, and starting to think on them, and then got life-sniped. Since they're still here, I wanted to give them another go. 2025-03-25 16:41:25 <@x1101:matrix.org> these sound like they're *new* jobs (in addition to the existing ones), don't accept params (have them set already). 2025-03-25 16:42:01 <@orandon:ansible.im> exactly, these issues follow on from https://github.com/ansible/ansible-documentation/pull/2348 where we broke things up and created two reusable jobs for the build and deploy phases 2025-03-25 16:42:19 <@x1101:matrix.org> yeah, I _vaguely_ remember 2025-03-25 16:43:05 <@orandon:ansible.im> so the desired outcome would be to have two new workflows similar to https://github.com/ansible/ansible-documentation/blob/devel/.github/workflows/build-package-docs.yaml but without any inputs 2025-03-25 16:43:41 <@x1101:matrix.org> one builds devel and publishes to devel, the other builds devel and publishes to latest? 2025-03-25 16:43:58 <@x1101:matrix.org> (that I'm less clear on, both the what and the why) 2025-03-25 16:44:56 <@orandon:ansible.im> the other builds whatever the latest version is and publishes to that branch. what constitutes "latest" is an RTD project setting. at the moment the "latest" version is `11` 2025-03-25 16:45:23 <@orandon:ansible.im> that build gets deployed to this branch: https://github.com/ansible-community/package-doc-builds/tree/11 2025-03-25 16:46:09 <@orandon:ansible.im> and from there, RTD builds kicks off whenever there is a push. the RTD job essentially just copies the generated build artifacts across. there's not really a build as such. 2025-03-25 16:47:56 <@orandon:ansible.im> during the release process when the latest version changes, one of the maintainers will need to update the workflow that you create to change the version to match whatever the current latest is, for instance when we update for Ansible 12. the maintainer will also need to go into the RTD project and set the default version for the latest build in the settings, but that's a separate task. 2025-03-25 16:48:23 <@orandon:ansible.im> so all that is to say that "latest" is really just a version number 2025-03-25 16:48:53 <@x1101:matrix.org> but a version number hard-set in the builds, and then updated when a new "latest" goes live 2025-03-25 16:49:37 <@x1101:matrix.org> I *think* I have it now. I'll start working on them and get some PRs going for disucssion and improvement. I'll drop comments on both 2025-03-25 16:50:00 <@orandon:ansible.im> sounds good. thanks for picking those up! 2025-03-25 16:50:39 <@orandon:ansible.im> feel free to ping me here too if you have any other questions 2025-03-25 16:50:59 <@orandon:ansible.im> I actually need to run now and take my kid to her after school thing 2025-03-25 16:51:27 <@orandon:ansible.im> samccann: do you mind if I leave the rest to you or should we just end the meeting a bit early? 2025-03-25 16:52:11 <@samccann:ansible.im> I can do a quick open floor. Thanks! 2025-03-25 16:52:12 <@orandon:ansible.im> got to run now for reals. thanks all! 2025-03-25 16:52:16 <@samccann:ansible.im> !topic Open Floor 2025-03-25 16:52:23 <@x1101:matrix.org> \o 2025-03-25 16:52:28 <@samccann:ansible.im> anyone have anything else in docs land to talk about today? 2025-03-25 16:54:05 <@samccann:ansible.im> !endmeeting