15:01:43 #startmeeting Documentation Working Group aka DaWGs 15:01:43 Meeting started Tue Jun 14 15:01:43 2022 UTC. 15:01:43 This meeting is logged and archived in a public location. 15:01:43 The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 15:01:43 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:01:43 The meeting name has been set to 'documentation_working_group_aka_dawgs' 15:01:59 #topic opening chatter 15:02:01 @room Meeting time! Who is here to talk the docs? 15:02:09 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:02:58 briantist: around to talk docs today? 15:03:57 👋🏽 15:04:08 #chair Dule_Martins#0383 15:04:08 Current chairs: Dule_Martins#0383 samccann 15:04:10 and welcome! 15:04:45 So to explain a bit - the hashtag chair gives you the ability to add directly to the meeting minutes etc. We usually chair everyone who shows up. 15:05:31 sometimes we get a handful of people... sometimes I'm talking to myself ;-) But today, at least we can talk to each other! 15:06:20 o/ (partially here, I can talk about how little I know about docs 😅 ) 15:06:32 #chair cybette 15:06:32 Current chairs: Dule_Martins#0383 cybette samccann 15:06:40 Just to ask, who are those expected to be here? 15:06:47 hah! we can make you a comfy cushion then! 15:07:16 In general, it's whomever might be available. With people having meeitngs, being in different timezones etc, we don't get a lot of people at this exact time. 15:07:44 In general as a project, Ansible has been moving to more asynchronous discussions and decision-making 15:08:02 you can see that here - https://github.com/ansible-community/community-topics/issues 15:08:39 and there have been a few docs discussions there. I 'think' I opened most of the docs ones, but not all. You can search there for me as the author if you want to see most of the docs discussions 15:08:44 I think generally we are also trying to encourage more async comunications, to be less dependent on such meetings (although they are still useful for certain discussions) 15:08:53 yep. 15:09:02 Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1148870651 15:09:09 #topic Explaining this meeting 15:09:30 Since we have some new folks who are reading along or will go back later to review, I want to explain the meeting a bit. 15:10:19 the hashtags are commands that the ..erm... meeting bot (fedorabot something or other) uses to create meeting minutes. Topics end up as headings, and we have info for important tidbits we want in the meeting, and lastly, we have action for creating action items. 15:10:44 This is an example of the meeting minutes from last week - https://github.com/ansible/community/issues/643#issuecomment-1142330915 15:10:58 You don't have to stay for all of the meeting, or any of the meeting. It's come and go as you have the time. Anything important is in the meeting minutes that you can review if you want. 15:11:29 Lastly, we split this time between actual docs discussions, and docs tooling (the stuff that builds the docs). 15:11:57 ok moving on ;-) 15:12:13 great overview samccann ! 15:12:15 (and btw, anyone can type at any time. There are no rules on who can say what when) 15:12:36 Oh and we have an Open Floor section at the end to bring up anything docs-related that we haven't covered. 15:12:41 ok.. moving on for realz 15:12:46 #topic Documentation updates 15:12:55 #info revamped getting started published! - https://docs.ansible.com/ansible/devel/getting_started/index.html 15:13:19 I might have said that last week, but it's a Big Deal so saying it again :-) Don isn't here today but did a great job revamping that guide! 15:13:51 as part of that, we moved some files around, so we have to put http redirects in place. (Our goal is to never give someone a 404 because we moved docs around). 15:14:01 #info need reviews of redirects for traffic from old location to new. It's a private github repo (boo) but see this pastbin https://github.com/ansible-community/github-docs-buil 15:14:23 so if anyone is good at https redirects (or regex expressions) ^^ 15:14:50 We've tested it out and it seems to work, but ya know, I'm always worried I'll create a redirect blackhole at some point. Probably at 5pm on a Friday :-) 15:15:14 lol 15:15:36 should we share the updated guide in Bullhorn? 15:15:49 hmm I thought I did? but yeah we should 15:16:12 #action samccann to get the new getting started guide in the bullhorn newsletter 15:16:33 So to explain, we have a weekly newsletter called the Bullhorn where we can add updates for whatever might be of interest to ansible users or developers 15:16:38 at least not in the last couple of issues (anything further back I may have forgotten :P ) 15:16:53 ok then yeah we definitely didn't! 15:17:17 I'll see if Don Naro wants to do it since he did the work (and deserves the bullhorn fame!) 15:17:24 sounds great, thanks! 15:17:42 he's got a semi-permanent conflict with this meeting time so sends his regrets. 15:18:11 #topic Ansible OS Docs on this week's Twitter Space! 15:18:26 Dule_Martins#0383: did you want to give a short update on what this is and how people can join? 15:19:22 hehe 15:19:25 talking to myself 15:20:06 Anyway, I think he may have gone offline. it's later in his neck o the woods. So I'll attempt to summarize 15:20:55 #info community-writers team is hosting a meeting on the Write the Docs NG twitter space this Friday, covering what is open source, docs, and how to use Ansible as an introduction to contributing to opensource projects 15:21:11 with our very own cybette and gundalow talking about it all 15:21:20 * gundalow waves 15:21:29 #chair gundalow 15:21:29 Current chairs: Dule_Martins#0383 cybette gundalow samccann 15:21:56 do either of you have info on how people can join if interested? If not, I can try to sneak it into the meeting minutes later when we get details. 15:22:03 All I know is you have to have a twitter account :-) 15:22:30 yeah one moment 15:22:30 coolness 15:22:39 https://twitter.com/NgDocs/status/1533785549806477312 15:22:55 #link https://twitter.com/NgDocs/status/1533785549806477312 15:23:29 ok should be fun. possibly available later for a download as well. 15:24:33 #info To participate in the Twitter Space live, log in with your Twitter account and join https://twitter.com/i/spaces/1mrGmarvpdLGy on June 17 at 19:30 WAT/UTC +1 15:24:46 cool thanks!! 15:25:10 #info The recording will be available after the event for 30 days 15:25:19 \o/ 15:25:44 ok moving on 15:25:51 #topic Docs updates again 15:25:56 * samccann lacks ideas for topic headings 15:26:19 #info Ansible 6 goes out in a week so we're staging docs etc in preparation. 15:26:39 #info plan going forward is to keep latest and devel docs in sync (aka backports). Wish us luck! 15:27:28 ^^ reason for that, beyond the obvious, is it seems people really didn't like that we have a handful of pages we only published/kept updated/ on devel docs. It was confusing. So we are attempting to keep up with weekly docs backports instead. 15:28:20 ^^ reason for THAT - we don't have a docsite for 'unversioned' docs (yet). So all are docs have to have a version in the url. Even though things like releast/maintenance and porting guides (and community guides... and probably the developer guide in large portions) are not really version-specific. 15:28:39 s/all are/all our/g 15:29:00 #info - if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board. 15:29:13 (cuz that's exciting so want to keep reminding folks of it) 15:29:55 #topic doctools 15:30:13 Explaining a bit - We have some 300+ RST pages for our guides. Then we have some 3000+ module/plugin pages that are generated from the docstrings embedded in python files and scattered across 90+ repositories. 15:30:24 A lot of what we cover in this section relates to that workflow, problems, enhancements, etc. 15:31:02 I don't think anyone is around today to answer the following question but... 15:31:38 #info does ansible/ansible CI only test the core docs? We now have multiple rst pages that only exist in Ansible package docs and I worry we aren't getting CI testing on them anymore. 15:31:44 To explain... ;-) 15:32:05 We have two docsites - docs.ansible.com/ansible (Ansible the package, including core docs and all the collection docs) 15:32:25 and docs.ansible.com/ansible-core - which is only the core docs and the builtin collection. 15:32:51 As time has gone by, we got fancier and fancier on excluding rst files from the core docs because they don't reflect what a user gets in `ansible-core` by itself. 15:33:29 But I think those exclusions mean they aren't going through the github CI either now. So that's a problem to solve. 15:33:59 #action samccann open a community-topic to discuss docs and CI and how to get CI testing on excluded (aka package only) docs 15:34:08 so that's one we'll have to cover async for sure. 15:34:15 And one more for the meeting minutes... 15:34:21 #info might be time to update our requirements packages? sphinx/rstcheck are advancing, as is antsibull-docs, amongst others. 15:35:19 To explain... ;-) we have a set of required packages to build our docs. The obvious ones are sphinx, that creates the HTML, rstcheck, that does the basic RST lintin, and antsibull-docs, that pulls in all those collection python docstrings and creates RST files to sphinx canturn them into HTML 15:36:08 Every so often, we want to update to the most recent packages so we don't get woefully outdated. But this also impacts test containers the the core team maintains. so we can't do it willy-nilly, but we can do it in devel as that is in active ...wait for it... development now ;-) 15:36:31 ... and I think i've slipped into talking to myself... so gonna... 15:36:36 #topic OpenFloor 15:36:46 If anyone is following along, here's the time to bring up anything in docs land. 15:37:10 got a question? a PR you want to move along, and issue? here's the time to mention it 15:37:46 we appreciate you talking to yourself and providing great info! I think we should share the log of this meeting as a quick guide to the current state of Ansible docs :) 15:37:56 hahaha 15:37:57 that'd work! 15:38:51 it's hard to tell if this is just becoming the wrong time for people to participate, or if it's part of the general trend toward asynch discussions. But this isn't the first time where i'm mostly chatting to myself of late. 15:39:49 of course there are not the massive docs changes (aka move to collections etc) that we were working through a year ago, so could just be.. all's quiet on the docs front in a good way 15:40:04 I remember the meeting time was changed last year? was it due to daylight savings or was the previous time also a "wrong time"? 15:40:16 anyway we'll definitely mention DaWGs (and this meeting) etc. in the twitter space this Friday 15:40:20 we tend to go along with daylight savings times yean 15:40:46 I'm in another another meeting, and hacking some stuff in 3rd window 15:41:30 but it's possible it's just not a convenient time. I won't ping him directly, but I know felix is a common participate but it hits right around the time he's on a train etc. and Don has a meeting at this time now regularly etc etc. 15:41:30 Maybe in a month or so we ask folks if this is still a good time 15:41:31 sounds like a plan stan 15:41:31 Also more async is good 15:41:54 agreed. We get more attention on async topics from people who aren't regularly in this meeting slot. 15:42:10 https://github.com/orgs/ansible-community/projects/3/views/1?layout=board 15:42:11 Shows 8 things done, which is brilliant 15:42:59 oh yeah, the community-writers have been a real boon (that's you discord peeps!!) 15:43:33 and that's only in the two weeks since we created the project board! they had some 30+ contributions prior to that 15:44:36 oh that's something we should ask Divine or Dule_Martins#0383 to pull together for the Twitter Space meeting - how many contributions to date. I think they did that before 15:45:09 amazing contributions! 💯 15:45:51 ok does anyone have anything else to add before we end the meeting? 15:46:48 ok then! 15:46:54 #endmeeting