15:04:50 #startmeeting Documentation Working Group aka DaWGs 15:04:50 Meeting started Tue Apr 11 15:04:50 2023 UTC. 15:04:50 This meeting is logged and archived in a public location. 15:04:50 The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 15:04:50 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:04:50 The meeting name has been set to 'documentation_working_group_aka_dawgs' 15:04:55 hi all 15:05:00 @room Meeting time! Who is here to talk the docs? 15:05:01 welcome sutapa_b 15:05:10 o/ 15:05:18 I was about to ask about the meeting. 15:05:23 #chair acozine Don Naro 15:05:23 Current chairs: Don Naro acozine samccann 15:05:35 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 o/ 15:05:44 o/ 15:05:49 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 #chair sutapa_b 15:05:56 Current chairs: Don Naro acozine samccann sutapa_b 15:06:05 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 If you have any questions sutapa_b , pipe in anytime and ask! 15:06:27 happy to have new folks join us! 15:06:36 sure :) thank you 15:07:08 felixfontein: briantist around to talk docs today? 15:07:09 #info official agenda at https://github.com/ansible/community/issues/678#issuecomment-1496482644 15:08:07 We have no open action items so.. woot! 15:08:32 #topic Documentation Updates 15:08:39 We have an interesting thing to talk about today! 15:08:56 So we have a couple of Ansible projects that are looking for community help on their docs. 15:09:21 huzzah for closing all the action items! 15:09:22 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 1 - creating the scaffolding (mkdocs and readthedocs) 15:09:45 2 - Editing the existing files so they are good to publish 15:10:24 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 Which projects are we talking about? 15:11:12 #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 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 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 worth trying it, I'd say 15:13:03 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 is there a time slot that would work well for folks who often can't make it to this meeting? 15:13:34 I don't know eda at all 15:14:21 if there is office hours for doc tooling I would be happy to join 15:14:42 What time works for you sutapa_b ? 15:15:01 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 mostly for questions,help and we could use github issues for planning asynchronously etc 15:15:38 because I know it's hard to get a group here all at the same time etc 15:16:13 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 I am guessing people may have preferences but +/- of 1 hour around this time should work for me in general 15:16:55 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 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 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 sure thing! 15:18:26 little bites and all 15:18:32 :-) yep 15:19:07 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 #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 are there tickets for the docs work in those two projects? 15:20:03 no not yet. I'll create some after this meeting 15:20:08 awesome 15:20:16 #action samccann to create tracking issues on awx operator docs effort 15:20:46 I'll do better at remembering if I leave a ticket open in a browser tab 15:21:03 hah yeah 15:21:33 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 okay moving on 15:23:07 Don Naro: anything to update on the docsite? 15:23:21 #info new docsite is going well... very few people switching to the old site 15:23:55 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 nice! 15:24:51 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 those are encouraging stats 15:24:57 and it doesn't seem like anyone has screamed about the new layout yet 15:24:59 Are you open for others picking up issues at this point? 15:25:19 yeah, totally. I've been open to that since the contrib summit. 15:25:27 because we can always highlight some or mark some 'easyfix' to get community help if you're ready 15:25:27 cool! 15:25:33 one thing I want to start doing is mapping out more journeys 15:25:51 #action oraNod to review open issues on docsite and mark some easyfix or worth highlighting in this channel 15:25:58 the docsite now is really just for core and collections but there is the whole ecosystem to consider 15:26:31 sutapa_b: we're talking about his https://github.com/ansible/jinja-docsite 15:26:48 I mention because it's another area that is more docs tooling so might be of interest 15:27:30 okay reviewing. 15:27:56 * acozine AFK 10 15:28:06 and you can always ask things in this channel anytime anywhere. People will find it when they get online etc 15:28:24 or if you find an issue that's interesting you can ask questions directly in the github issue. whichever works best 15:28:56 hmm let's see.. what else 15:29:11 #info docs archiving nearly complete! Will redirect 2.7 soon and may stop there 15:29:24 ^^ mostly because I can't build 2.8 and it may not be worth the effort. 15:29:25 samccann: sure :) 15:30:00 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 and I don't think we can archive 2.9 for AGES because of customers using it etc. 15:31:16 hm... oh another thing coming 15:31:35 #info working on a shared documentation style guide (rst and md) that can be used across all ansible projects 15:31:56 if anyone wants to get their style guide groove on, happy to welcome the help 15:32:27 the existing guide is https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html 15:33:14 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 #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 re: archiving docs 15:35:20 hmm... that's about all I had today. Much quieter now that the docsite launched! 15:35:37 I noticed that the old docsites have links on them that say "for older docs, see the archive" 15:35:53 but the latest docs don't have that, or at least not in the same spot 15:36:01 is there a link somewhere? 15:36:20 yeah if you scroll down the page a little you should see the link to the archive 15:36:29 https://docs.ansible.com/core.html 15:36:39 it's on the core page for sure 15:37:46 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 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 https://docs.ansible.com/archive/ansible/2.3/ 15:38:45 there in the upper left box 15:38:54 anyway, thanks for the pointers 15:39:18 oh, even funnier, that link goes to the main docsite! 15:39:30 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 I doubt you'd ever get it to build at this point 15:39:54 yep 15:40:02 #topic Open Floor 15:40:22 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 quiet today... :-) 15:42:00 nothing from me anyway. thanks samccann 15:42:09 oh I have a random topic to think about 15:42:36 The community WG went to a model of async discussions. We haven't done that as much here. 15:42:55 Tho we do for big things like creating the new docsite and journeys etc 15:43:16 'some day' we'll have a forum, so we should think about how we want to use it as well 15:43:47 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 what else would be involved in async discussions about docs? 15:44:58 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 and the other way as well... something comes up here and we move it to discussion for async etc 15:46:27 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 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 for those wondering - ansible will someday have a forum like this fedora one - https://discussion.fedoraproject.org/ 15:48:39 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 and discourse meta (their own forum for their project) does have a documentaiton category - https://meta.discourse.org/ 15:50:11 so ..something to think about for sure on which way we want to go 15:50:51 huh, those two views are pretty different 15:51:27 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 tho will likely depend on what other WG do as well. 15:52:22 we'd have to consider if a docs category that covers all ansible projects is sustainable or not for example 15:53:07 anyhooo that's about all I have for this week. Anything else before we end the meeting? 15:53:17 can't think of anything 15:53:32 #endmeeting