15:01:32 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:32 <zodbot> Meeting started Tue Jul 11 15:01:32 2023 UTC.
15:01:32 <zodbot> This meeting is logged and archived in a public location.
15:01:32 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:32 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:32 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:43 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:51 <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:01:53 <acozine> o/
15:01:55 <oranod> o/
15:02:02 <oranod> down low
15:02:08 <samccann> #chair acozine Don Naro
15:02:08 <zodbot> Current chairs: Don Naro acozine samccann
15:02:09 <samccann> heh
15:02:19 <samccann> To any newcomers - again, welcome. We chair all attendees as a way of recognizing your time spent here. And it opens it up for people to add to the meeting minutes with commands like #info or #link (to add a link)
15:02:28 <samccann> 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!)
15:02:41 <samccann> official agenda at https://github.com/ansible/community/issues/678#issuecomment-1620459192
15:03:20 <samccann> #topic Moving docs out of ansible/ansible
15:03:34 <samccann> #info All seems ready to move forward with docs in the new repo.
15:03:54 <samccann> Anyone see anything that should stop/postpone this?
15:04:19 <samccann> The goal is to remove the /docs folder from ansible/ansible today and call this done. So this is the last check before we do that
15:04:47 <acozine> I have the same reservations I have had all along, but nothing new and nothing that I'd consider a blocker.
15:04:52 <oranod> #link https://hackmd.io/c9SEj2FaRvKF5UhXNl9NtA#To-do-before-split
15:04:58 <samccann> Thanks acozine
15:05:29 <oranod> I think we've gone through all the to do items so nothing I can see
15:05:32 <samccann> #info to maintain technical stewardship of the docs, the core team will add any PRs that need docs to a new project board and the docs folks will convert that to an issue in the new repo
15:05:56 <samccann> #info we will also add a label of techreview to docs PRs where we need someone technical to come in and review the change before we merge
15:06:10 <samccann> ^^ is how we hope to maintain the technical accuracy of it all
15:06:46 <samccann> ok so I'll let the core team know we are good to go on this change. It's scary, but after 3+ weeks, seems we are ready
15:06:58 <briantist> o/
15:07:11 <oranod> aloha briantist
15:08:01 <acozine> #chair briantist
15:08:01 <zodbot> Current chairs: Don Naro acozine briantist samccann
15:08:07 <TVo[m]> Hi, I'll be a fly on the wall today, I am on another community call
15:08:15 <oranod> hey TVo
15:08:18 <samccann> #chair TVo
15:08:18 <zodbot> Current chairs: Don Naro TVo acozine briantist samccann
15:08:25 <samccann> even flies deserve chairs here :-)
15:08:29 <oranod> #link https://github.com/ansible/ansible-documentation/issues/36
15:08:44 <oranod> one other thing I'd quickly like to point out before we move on to another topic
15:09:09 <oranod> #info we've also described some techniques/strategies to try and help reduce contributor overhead
15:09:21 <oranod> as well as the review process and the tech review label
15:10:13 <oranod> hopefully that will help go some way to mitigating the dangers of losing contributors, which is what I think you had reservations about acozine
15:11:29 <acozine> my concern is not about losing community docs contributors, it's about losing docs input from the developers (RH or community) who are maintaining and expanding the codebase
15:11:44 <acozine> and I do hope your process will help
15:12:45 <samccann> on the plus side, we have a lot of community engagement in setting up this new docs repo. That part is promising
15:12:56 <oranod> yeah I think I phrased it kind of wrong there. not so much losing contributors but adding overhead that will lead to loss of input.
15:14:49 <samccann> ok sounds like no stoppers
15:15:04 <sutapa_bhattacha> o/ sorry I'm late.
15:15:09 <samccann> #info will inform core they can nuke the /docs folder in ansible/ansible
15:15:15 <samccann> #chair sutapa_bhattacharjee
15:15:15 <zodbot> Current chairs: Don Naro TVo acozine briantist samccann sutapa_bhattacharjee
15:15:19 <samccann> welcome welcome!
15:15:24 <oranod> hey sutapa_bhattacharjee
15:16:04 <samccann> #topic EE getting started and home for Ecosystem docs
15:16:34 <samccann> I think this came up last week. We have the EE getting started guide ready to go, but there was some chatter I guess about whether we should have a separate repo for docs that cover more than one project?
15:16:55 <samccann> #info do we want a separate repo for ecosystem docs like the EE getting started? (docs that cover more than one project...
15:16:59 <oranod> #link https://github.com/ansible/ansible-documentation/pull/18#issuecomment-1628779074
15:17:26 <samccann> on the one hand, I like the idea. It keeps the Ansible docs for... the ansible package so to speak.
15:17:32 <oranod> I was thinking a separate repo like ansible/ecosystem-documentation but I think I'm more of a fan of the idea of keeping it all under ansible/ansible-documentation
15:17:50 <samccann> on the other hand, a separate 'ecosystem docs' set of guides would be 'someplace else' and harder for people to notice they exist
15:18:10 <samccann> I guess it comes to a higher level vision
15:18:26 <samccann> Do we want docs.ansible.com/ansible to cover more than core and collections?
15:18:51 <acozine> Also, the more repos we need to review, the more likely we'll have issues and PRs that go unnoticed.
15:18:54 <briantist> I might be wrong, but my gut feeling is that it's easier to keep things together up until the point where the balance tips and it's "better" (for some definition of better) to  move it
15:18:56 <samccann> and if so, how do we 'version' something like the EE guide when it's not tied to core or Ansible package releases
15:19:21 <briantist> so maybe if we kind of vaguely keep in mind "there's a possibility for things to move out of this repo" that's enough for now?
15:19:27 <acozine> Ah. EEs do seem to be version constrained.
15:19:41 <acozine> At least, I recently built an EE that would not run on my current version of Controller (AWX/Tower).
15:19:53 <samccann> well yes and no. They don't apply to the core/package version, but we could just have these as 'unversioned' guides
15:20:14 <acozine> (I realize that adds a level of complexity beyond what we're already discussing with regard to versioning)
15:20:19 <samccann> meaning we'll only ever support a 'latest' version. and it would include the builder/navigator versions it was tested with in the docs somewhere
15:21:01 <oranod> what if we put a structure like this in `ansible/ansible-documentation` :... (full message at <https://libera.ems.host/_matrix/media/v3/download/libera.chat/0f17d4d0ba2dd867d85b576b436ea343204a4183>)
15:21:09 <samccann> acozine: builder v3 only works with..erm.. the most recently released controller version (as of a couple of weeks ago when it was released)
15:21:42 <samccann> Don Naro: we could.. that's a whole lotta redirects we'd need to track
15:21:44 <oranod> I know we're kind of talking about versioning now but I've come to the opinion that having multiple repos would be a mistake
15:22:02 <oranod> I'm not sure we would have that many redirects in the end
15:22:07 <samccann> yeah seems we are in agreement on that one (no separate repo)
15:22:24 <samccann> on redirects - every file/folder move is a readirect.
15:22:42 <oranod> for Andrei's EE tutorial PR, I had the question if we could keep the content on devel until we work out the layout
15:23:02 <samccann> #agreed we will not have a separate docs repo for ecosystem docs for now (like the EE getting started guide). Adds too much complexity
15:23:04 <oranod> that should help prevent too much churn and the need for extra redirects
15:23:41 <samccann> ah so we use EE guide as the start of a new 'restructure' of the directories ... that makes sense
15:23:50 <samccann> kind of like we did when you revamped the user guide into multiple guides
15:27:05 <oranod> it's the start of a larger effort towards more ecosystem docs focused on tutorials and how-tos and I agree that it doesn't exactly belong in the package docs. but the real home doesn't exist yet either.
15:27:06 <oranod> it'd be great to get Andrei's PR merged to get some community soak time and provide the need for more EE docs while we spin up some more ecosystem docs
15:27:06 <oranod> like the devtools getting started
15:27:11 <samccann> ok sounds like a plan
15:27:36 <oranod> have we ever done that before? publishing to devel only?
15:28:21 <oranod> as it won't be on latest I thought we could maybe send it to the Bullhorn as an "experimental" piece of content and maybe get some community feedback as well as potentially discovering additional ecosystem content
15:28:35 <oranod> maybe folks out there have How Tos that they'd love to see etc
15:28:57 <samccann> all your user guide changes were devel only so yes, we've done this before
15:28:58 <oranod> personally I've been working on a how to with receptor but I don't know if it's any good
15:29:07 <samccann> devel does get some hits, just not as many
15:29:13 <oranod> oh snap. just like you said earlier. doh
15:29:23 <samccann> but if we also put up a PR on builder that points to the devel guide, it might get more attention
15:29:40 <oranod> ching ching
15:29:55 <samccann> ok are we ready to move on?
15:30:17 <samccann> #topic Documentation Updates
15:30:25 <samccann> #info awx operator work continuing for docs
15:30:47 <samccann> big shout out to sutapa_bhattacharjee for getting the mkdocs scaffolding ready! that was a big step forward
15:31:52 <samccann> and another shoutout to 0xanon.eth for setting the strategy and leading the effort to convert the big ol readme into a series of docs files!
15:32:03 <samccann> I have a batch of PRs to review for that later today I hope. but great progress
15:32:24 <samccann> oh I should have info'd both
15:32:34 <samccann> #info big shout out to
15:32:34 <samccann> sutapa_bhattacharjee
15:32:34 <samccann> for getting the mkdocs scaffolding ready! that was a big step forward
15:32:45 <samccann> #info and another shoutout to
15:32:46 <samccann> 0xanon.eth
15:32:46 <samccann> for setting the strategy and leading the effort to convert the big ol readme into a series of docs files!
15:33:05 <samccann> i bet that didn't work at all... I'll have to manually fix it
15:33:09 <sutapa_bhattacha> 😀 Thank you.
15:33:15 <acozine> w00t for 0xanon.eth and sutapa_bhattacharjee !
15:33:29 <M0xanoneth0[m]> Thank you 👏
15:33:36 <samccann> it's exciting to have stuff run entirely by community folks!
15:33:51 <oranod> great work sutapa_bhattacharjee and 0xanon.eth
15:35:45 <samccann> ok I think sutapa_bhattacharjee has volunteered to dig into the command cheatsheet as well. Let us know where/how we can help you with that effort.
15:36:19 <samccann> my guess is one PR per command and once you create it, we will get feedback on which flags etc are important/used the most etc
15:37:08 <sutapa_bhattacha> samccann: Yes, I'm waiting for some response on that issue.
15:38:22 <samccann> speaking of issues, I'll be moving them over to the new docs repo soon. in case y'all see noise about that happening
15:38:26 <acozine> What do you need sutapa_bhattacharjee ?
15:38:33 <samccann> no changes, just a new place to look for issues
15:40:06 <sutapa_bhattacha> acozine: I need to know which flags are most important so that it can be added in cheatsheet.
15:41:38 <acozine> Ah, I don't have an answer for that, but if I were doing the page, I'd pick a command, think about what I might use it for, then read the CLI documentation and make a guess about which flags I would most want to use.
15:41:52 <samccann> yeah I'd do the same
15:41:58 <acozine> Then I'd create a PR and ask for feedback from folks who use that command a lot.
15:42:04 <samccann> pick the first command on the list that isn't checked off yet
15:42:57 <sutapa_bhattacha> samccann: okay I'll do that.
15:43:27 <samccann> coolness!
15:43:35 <samccann> #topic Open Floor
15:43:48 <samccann> Anyone else have docs-related things to discuss today?
15:44:28 <samccann> I think there's a new version of antsibull-docs either released or on PR ?
15:44:40 <oranod> I've got a couple things to mention with that jinja/docsite but I don't want to hog the dance floor
15:44:49 <samccann> heh
15:44:54 <oranod> yes antsibull-docs 2.3.0 I believe
15:44:58 <samccann> 🕺
15:45:39 <samccann> so devel docs must already be using it then. I think we fixed it so it's back to open requirements, right?
15:46:35 <oranod> my head has been a bit melted with the requirements lately. it's fine though.
15:46:52 <oranod> pretty sure it's pinned to 2.3.0 now if that's what you mean though
15:47:04 <oranod> * pretty sure it's pinned to 2.3.0 now if that's what you mean
15:47:09 <samccann> ok I can go look later.
15:47:37 <oranod> #link https://github.com/ansible/jinja-docsite/pull/122
15:47:38 <samccann> my guess is if felixfontein has a PR waiting on us, he'll remind us soon :-)
15:48:02 <oranod> #info I've sent a PR to remove the oldsite toggle as agreed at the meeting before last
15:48:14 <oranod> that should be ready for review
15:48:22 <samccann> cool
15:48:36 <samccann> I think the only way to 'test' is to build locally from that PR right?
15:48:38 <oranod> there are a few other PRs in the jinja/docsite queue that are ready for review too
15:48:51 <oranod> there's the gh action too
15:49:19 <oranod> no wait. I see what you mean. test the PR. yes, I'll set up PR previews when we take over ansible/docsite
15:49:31 <samccann> ok cool. that will help for sure
15:51:45 <oranod> the steps to get there, imo and I'd appreciate anyone's feedback, will be to drop the toggle and get the templates updated (basically merge all the PRs there now). after that put all the source on the main branch of ansible/docsite, set up PR previews on read the docs as we do for the community website, and deploy from a new prod branch in ansible/docsite
15:52:03 <oranod> #link https://github.com/ansible/jinja-docsite/pull/130
15:53:24 <oranod> #info last week I went through all the issues and rewrote the jinja templates to fully separate the data from the html. so now, to add core translations for example, you'd only need to add a few new fields to the yaml files in the data folder
15:53:42 <oranod> any and all review on those PRs would be welcome, thanks
15:54:41 <samccann> cool
15:54:58 <samccann> ooch I have another meeting in 5 min. Anything else before we close?
15:55:40 <samccann> ok thanks everyone!
15:55:44 <samccann> #endmeeting