15:04:50 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:04:50 <zodbot> Meeting started Tue Apr 11 15:04:50 2023 UTC.
15:04:50 <zodbot> This meeting is logged and archived in a public location.
15:04:50 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:04:50 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:04:50 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:04:55 <oranod> hi all
15:05:00 <samccann> @room Meeting time! Who is here to talk the docs?
15:05:01 <oranod> welcome sutapa_b
15:05:10 <oranod> o/
15:05:18 <sutapa_b[m]> I was about to ask about the meeting.
15:05:23 <samccann> #chair acozine Don Naro
15:05:23 <zodbot> Current chairs: Don Naro acozine samccann
15:05:35 <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:05:39 <acozine> o/
15:05:44 <sutapa_b[m]> o/
15:05:49 <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:05:56 <samccann> #chair sutapa_b
15:05:56 <zodbot> Current chairs: Don Naro acozine samccann sutapa_b
15:06:05 <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:06:17 <samccann> If you have any questions sutapa_b , pipe in anytime and ask!
15:06:27 <samccann> happy to have new folks join us!
15:06:36 <sutapa_b[m]> sure :) thank you
15:07:08 <samccann> felixfontein: briantist around to talk docs today?
15:07:09 <samccann> #info official agenda at https://github.com/ansible/community/issues/678#issuecomment-1496482644
15:08:07 <samccann> We have no open action items so.. woot!
15:08:32 <samccann> #topic Documentation Updates
15:08:39 <samccann> We have an interesting thing to talk about today!
15:08:56 <samccann> So we have a couple of Ansible projects that are looking for community help on their docs.
15:09:21 <acozine> huzzah for closing all the action items!
15:09:22 <samccann> basically, they have a few .md files and a readme, and what they want is a docsite up on readthe docs. So  there will be two components to this
15:09:36 <samccann> 1 - creating the scaffolding (mkdocs and readthedocs)
15:09:45 <samccann> 2 - Editing the existing files so they are good to publish
15:10:24 <samccann> My goal is to find people in community willing to take on both. We have enough knowledge in general that we can get help where needed if someone for example wants to take on the scaffolding for a docsite but has never done it etc
15:11:12 <acozine> Which projects are we talking about?
15:11:12 <samccann> #info awx operator looking for docs help to create a docsite and split up the big readme into .md files for said docsite - https://github.com/ansible/awx-operator
15:11:51 <samccann> I'll create issues etc for that later, but ws thinking it might be fun to run this as a mini project outside of this meeting slot. Like maybe Thursday afternoons
15:12:32 <samccann> as an 'open office hrs' for docs. We've mentioned that before because this meeting can get very technical on doc tooling etc so not a lot of opportunity for newer folks to get a feel for docs in general. What do y'all think?
15:12:55 <acozine> worth trying it, I'd say
15:13:03 <samccann> acozine: awx operator and eda are the two. I figured we'd do it one a time and see how it goes?
15:13:14 <acozine> is there a time slot that would work well for folks who often can't make it to this meeting?
15:13:34 <acozine> I don't know eda at all
15:14:21 <sutapa_b[m]> if there is office hours for doc tooling I would be happy to join
15:14:42 <samccann> What time works for you sutapa_b ?
15:15:01 <samccann> because we could just in general say 'chats on Thursdays' and people come in and out as they get a chance etc
15:15:23 <samccann> mostly for questions,help and we could use github issues for planning asynchronously etc
15:15:38 <samccann> because I know it's hard to get a group here all at the same time etc
15:16:13 <samccann> sutapa_b: if you're more interested in docs tooling this is the time lol. Most of these meetings end up talking about tooling stuff
15:16:21 <sutapa_b[m]> I am guessing people may have preferences but +/- of 1 hour around this time should work for me in general
15:16:55 <samccann> but if you are more on the technical side, would you be interesting in helping create the scaffolding so to speak for the docsite? It's not quite coding, but it's definitely not 'words on paper' so to speak
15:17:21 <samccann> we have multiple other projects you could learn from, but no worries if that's not something you want to grab hold of right away etc
15:18:16 <sutapa_b[m]> I can and want to go in that direction as well, however for now let's start small, if that's okay :)
15:18:23 <samccann> sure thing!
15:18:26 <sutapa_b[m]> little bites and all
15:18:32 <samccann> :-) yep
15:19:07 <samccann> So sounds like the idea of using Thursdays to coordinate wherever we need to chat 'live' so to speak is good. Separates it from this general meeting a bit.
15:19:50 <samccann> #info we will coordinate the project in github for async planning etc and use Thursdays on #docs matrix/irc channel for when we need to chat live for questions etc
15:19:52 <acozine> are there tickets for the docs work in those two projects?
15:20:03 <samccann> no not yet. I'll create some after this meeting
15:20:08 <acozine> awesome
15:20:16 <samccann> #action samccann to create tracking issues on awx operator docs effort
15:20:46 <acozine> I'll do better at remembering if I leave a ticket open in a browser tab
15:21:03 <samccann> hah yeah
15:21:33 <samccann> same here. or frankly, I make google 'meetings' with myself and just add what I want to get done in that meeting slot so to speak.  I'm sure there's better ways but anyway
15:22:28 <samccann> okay moving on
15:23:07 <samccann> Don Naro: anything to update on the docsite?
15:23:21 <samccann> #info new docsite is going well... very few people switching to the old site
15:23:55 <samccann> I don't have stats handy but when I checked yesterday - we had 2k visitors to docs.ansible.com, and maybe 70 to the oldsite (aka choosing the toggle to go back to the old way)
15:24:17 <acozine> nice!
15:24:51 <oranod> hey, not lots to update. I've some work to do on it later this week. I want to see about some refactoring. plus andersson007_ has opened a PR and issue that I'd like to start working on.
15:24:51 <oranod> those are encouraging stats
15:24:57 <oranod> and it doesn't seem like anyone has screamed about the new layout yet
15:24:59 <samccann> Are you open for others picking up issues at this point?
15:25:19 <oranod> yeah, totally. I've been open to that since the contrib summit.
15:25:27 <samccann> because we can always highlight some or mark some 'easyfix' to get community help if you're ready
15:25:27 <samccann> cool!
15:25:33 <oranod> one thing I want to start doing is mapping out more journeys
15:25:51 <samccann> #action oraNod to review open issues on docsite and mark some easyfix or worth highlighting in this channel
15:25:58 <oranod> the docsite now is really just for core and collections but there is the whole ecosystem to consider
15:26:31 <samccann> sutapa_b: we're talking about his https://github.com/ansible/jinja-docsite
15:26:48 <samccann> I mention because it's another area that is more docs tooling so might be of interest
15:27:30 <sutapa_b[m]> okay reviewing.
15:27:56 * acozine AFK 10
15:28:06 <samccann> and you can always ask things in this channel anytime anywhere. People will find it when they get online etc
15:28:24 <samccann> or if you find an issue that's interesting you can ask questions directly in the github issue. whichever works best
15:28:56 <samccann> hmm let's see.. what else
15:29:11 <samccann> #info docs archiving nearly complete! Will redirect 2.7 soon and may stop there
15:29:24 <samccann> ^^ mostly because I can't build 2.8 and it may not be worth the effort.
15:29:25 <sutapa_b[m]> samccann: sure :)
15:30:00 <samccann> As a reminder, we chose to archive older docs so we could redirect them all to latest and fix our google search results. That's basically done, even w/o 2.8
15:30:17 <samccann> and I don't think we can archive 2.9 for AGES because of customers using it etc.
15:31:16 <samccann> hm... oh another thing coming
15:31:35 <samccann> #info working on a shared documentation style guide (rst and md) that can be used across all ansible projects
15:31:56 <samccann> if anyone wants to get their style guide groove on, happy to welcome the help
15:32:27 <samccann> the  existing guide is https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html
15:33:14 <samccann> So we'll review that for possible extensions (without going too deep) and then add something for markdown where needed. I'd say more than 1/2 of the projects use md instead of rst today
15:34:57 <samccann> #info Always welcoming help on open issues https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs or easyfix issues https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs+label%3Aeasyfix
15:35:20 <acozine> re: archiving docs
15:35:20 <samccann> hmm... that's about all I had today. Much quieter now that  the docsite launched!
15:35:37 <acozine> I noticed that the old docsites have links on them that say "for older docs, see the archive"
15:35:53 <acozine> but the latest docs don't have that, or at least not in the same spot
15:36:01 <acozine> is there a link somewhere?
15:36:20 <oranod> yeah if you scroll down the page a little you should see the link to the archive
15:36:29 <samccann> https://docs.ansible.com/core.html
15:36:39 <samccann> it's on the core page for sure
15:37:46 <samccann> we get very few people using the archive (tho it's not zero!) so makes sense to keep the link, but not have it as prominent as it used to be so to speak
15:38:26 <acozine> oh, funny, I just looked and I think it's only the 2.3 docs that have the link I'm talking about, but that's where I started because they were in the issue
15:38:37 <acozine> https://docs.ansible.com/archive/ansible/2.3/
15:38:45 <acozine> there in the upper left box
15:38:54 <acozine> anyway, thanks for the pointers
15:39:18 <acozine> oh, even funnier, that link goes to the main docsite!
15:39:30 <samccann> yeah that existed on the old old pages. The archive didn't change the docs, just the url so to speak. I think I'd be tarred and feathered if I tried to edit somethign tat old
15:39:46 <acozine> I doubt you'd ever get it to build at this point
15:39:54 <samccann> yep
15:40:02 <samccann> #topic Open Floor
15:40:22 <samccann> Anyone have something they want to bring up or ask about? We have a few minutes left and I'm out of agenda items :-)
15:41:33 <samccann> quiet today... :-)
15:42:00 <oranod> nothing from me anyway. thanks samccann
15:42:09 <samccann> oh I have a random topic to think about
15:42:36 <samccann> The community WG went to a model of async discussions. We haven't done that as much here.
15:42:55 <samccann> Tho we do for big things like creating the new docsite and journeys etc
15:43:16 <samccann> 'some day' we'll have a forum, so we should think about how we want to use it as well
15:43:47 <acozine> this channel is quiet in general lately, but I think you've been posting links so folks who can't make the meetings can weigh in on the issues/questions of the day
15:44:41 <acozine> what else would be involved in async discussions about docs?
15:44:58 <samccann> yeah I can see us potentially using a similar model as the community wg - were we have some discussion topics in the forum, and then use this meeting to highlight them and chat live as a supplement
15:45:25 <samccann> and the other way as well... something comes up here and we move it to discussion for async etc
15:46:27 <samccann> I can see async discussions used to extend the docs WG beyond ansible-core and collections. So broader topics and highlighting need for help on all the other ansible projects over time etc
15:47:06 <samccann> but I'm not even sure if we'd have our own 'category' for docs, or just use tag to mark something as a docs thread in any category/project in the forum
15:47:48 <samccann> for those wondering - ansible will someday have a forum like this fedora one - https://discussion.fedoraproject.org/
15:48:39 <samccann> which I'll note doesn't have a category for docs  OR a docs tag, but does have a docs-team tag.. so... things to think about!
15:49:48 <samccann> and discourse meta (their own forum for their project) does have a documentaiton category - https://meta.discourse.org/
15:50:11 <samccann> so ..something to think about for sure on which way we want to go
15:50:51 <acozine> huh, those two views are pretty different
15:51:27 <samccann> yep. Not sure what ours would look like but I'd say in general, we'd want to decide if we wanted to ask for a category or just a tag or two
15:51:38 <samccann> tho will likely depend on what other WG do as well.
15:52:22 <samccann> we'd have to consider if a docs category that covers all ansible projects is sustainable or not for example
15:53:07 <samccann> anyhooo that's about all I have for this week. Anything else before we end the meeting?
15:53:17 <acozine> can't think of anything
15:53:32 <samccann> #endmeeting