15:01:43 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:43 <zodbot> Meeting started Tue Jun 14 15:01:43 2022 UTC.
15:01:43 <zodbot> This meeting is logged and archived in a public location.
15:01:43 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:43 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:43 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:59 <samccann> #topic opening chatter
15:02:01 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:09 <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:02:58 <samccann> briantist: around to talk docs today?
15:03:57 <Dule_Martins0383> 👋🏽
15:04:08 <samccann> #chair Dule_Martins#0383
15:04:08 <zodbot> Current chairs: Dule_Martins#0383 samccann
15:04:10 <samccann> and welcome!
15:04:45 <samccann> 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 <samccann> 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 <cybette_> o/ (partially here, I can talk about how little I know about docs 😅 )
15:06:32 <samccann> #chair cybette
15:06:32 <zodbot> Current chairs: Dule_Martins#0383 cybette samccann
15:06:40 <Dule_Martins0383> Just to ask, who are those expected to be here?
15:06:47 <samccann> hah! we can make you a comfy cushion then!
15:07:16 <samccann> 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 <samccann> In general as a project, Ansible has been moving to more asynchronous discussions and decision-making
15:08:02 <samccann> you can see that here - https://github.com/ansible-community/community-topics/issues
15:08:39 <samccann> 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 <cybette_> 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 <samccann> yep.
15:09:02 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1148870651
15:09:09 <samccann> #topic Explaining this meeting
15:09:30 <samccann> 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 <samccann> 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 <samccann> This is an example of the meeting minutes from last week - https://github.com/ansible/community/issues/643#issuecomment-1142330915
15:10:58 <samccann> 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 <samccann> Lastly, we split this time between actual docs discussions, and docs tooling (the stuff that builds the docs).
15:11:57 <samccann> ok moving on ;-)
15:12:13 <cybette_> great overview samccann !
15:12:15 <samccann> (and btw, anyone can type at any time. There are no rules on who can say what when)
15:12:36 <samccann> 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 <samccann> ok.. moving on for realz
15:12:46 <samccann> #topic Documentation updates
15:12:55 <samccann> #info revamped getting started published! - https://docs.ansible.com/ansible/devel/getting_started/index.html
15:13:19 <samccann> 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 <samccann> 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 <samccann> #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 <samccann> so if anyone is good at https redirects (or regex expressions) ^^
15:14:50 <samccann> 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 <cybette_> lol
15:15:36 <cybette_> should we share the updated guide in Bullhorn?
15:15:49 <samccann> hmm I thought I did? but yeah we should
15:16:12 <samccann> #action samccann to get the new getting started guide in the bullhorn newsletter
15:16:33 <samccann> 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 <cybette_> at least not in the last couple of issues (anything further back I may have forgotten :P )
15:16:53 <samccann> ok then yeah we definitely didn't!
15:17:17 <samccann> I'll see if Don Naro wants to do it since he did the work (and deserves the bullhorn fame!)
15:17:24 <cybette_> sounds great, thanks!
15:17:42 <samccann> he's got a semi-permanent conflict with this meeting time so sends his regrets.
15:18:11 <samccann> #topic Ansible OS Docs on this week's Twitter Space!
15:18:26 <samccann> Dule_Martins#0383: did you want to give a short update on what this is and how people can join?
15:19:22 <samccann> hehe
15:19:25 <samccann> talking to myself
15:20:06 <samccann> 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 <samccann> #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 <samccann> with our very own cybette and gundalow talking about it all
15:21:20 * gundalow waves
15:21:29 <samccann> #chair gundalow
15:21:29 <zodbot> Current chairs: Dule_Martins#0383 cybette gundalow samccann
15:21:56 <samccann> 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 <samccann> All I know is you have to have a twitter account :-)
15:22:30 <cybette_> yeah one moment
15:22:30 <samccann> coolness
15:22:39 <gundalow> https://twitter.com/NgDocs/status/1533785549806477312
15:22:55 <samccann> #link https://twitter.com/NgDocs/status/1533785549806477312
15:23:29 <samccann> ok should be fun. possibly available later for a download as well.
15:24:33 <cybette_> #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 <samccann> cool thanks!!
15:25:10 <cybette_> #info The recording will be available after the event for 30 days
15:25:19 <samccann> \o/
15:25:44 <samccann> ok moving on
15:25:51 <samccann> #topic Docs updates again
15:25:56 * samccann lacks ideas for topic headings
15:26:19 <samccann> #info Ansible 6 goes out in a week so we're staging docs etc in preparation.
15:26:39 <samccann> #info plan going forward is to keep latest and devel docs in sync (aka backports). Wish us luck!
15:27:28 <samccann> ^^ 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 <samccann> ^^ 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 <samccann> s/all are/all our/g
15:29:00 <samccann> #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 <samccann> (cuz that's exciting so want to keep reminding folks of it)
15:29:55 <samccann> #topic doctools
15:30:13 <samccann> 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 <samccann> A lot of what we cover in this section relates to that workflow, problems, enhancements, etc.
15:31:02 <samccann> I don't think anyone is around today to answer the following question but...
15:31:38 <samccann> #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 <samccann> To explain... ;-)
15:32:05 <samccann> We have two docsites - docs.ansible.com/ansible  (Ansible the package, including core docs and all the collection docs)
15:32:25 <samccann> and docs.ansible.com/ansible-core - which is only the core docs and the builtin collection.
15:32:51 <samccann> 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 <samccann> 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 <samccann> #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 <samccann> so that's one we'll have to cover async for sure.
15:34:15 <samccann> And one more for the meeting minutes...
15:34:21 <samccann> #info might be time to update our requirements packages? sphinx/rstcheck are advancing, as is antsibull-docs, amongst others.
15:35:19 <samccann> 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 <samccann> 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 <samccann> ... and I think i've slipped into talking to myself... so gonna...
15:36:36 <samccann> #topic OpenFloor
15:36:46 <samccann> If anyone is following along, here's the time to bring up anything in docs land.
15:37:10 <samccann> got a question? a PR you want to move along, and issue? here's the time to mention it
15:37:46 <cybette_> 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 <samccann> hahaha
15:37:57 <samccann> that'd work!
15:38:51 <samccann> 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 <samccann> 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 <cybette_> 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 <cybette_> anyway we'll definitely mention DaWGs (and this meeting) etc. in the twitter space this Friday
15:40:20 <samccann> we tend to go along with daylight savings times yean
15:40:46 <gundalow> I'm in another another meeting, and hacking some stuff in 3rd window
15:41:30 <samccann> 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 <gundalow> Maybe in a month or so we ask folks if this is still a good time
15:41:31 <samccann> sounds like a plan stan
15:41:31 <gundalow> Also more async is good
15:41:54 <samccann> agreed. We get more attention on async topics from people who aren't regularly in this meeting slot.
15:42:10 <gundalow> https://github.com/orgs/ansible-community/projects/3/views/1?layout=board
15:42:11 <gundalow> Shows 8 things done, which is brilliant
15:42:59 <samccann> oh yeah, the community-writers have been a real boon (that's you discord peeps!!)
15:43:33 <samccann> 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 <samccann> 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 <cybette_> amazing contributions! 💯
15:45:51 <samccann> ok does anyone have anything else to add before we end the meeting?
15:46:48 <samccann> ok then!
15:46:54 <samccann> #endmeeting