15:01:42 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:42 <zodbot> Meeting started Tue Apr 18 15:01:42 2023 UTC.
15:01:42 <zodbot> This meeting is logged and archived in a public location.
15:01:42 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:42 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:42 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:55 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:22 <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:32 <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:42 <sutapa_b[m]> o/
15:02:43 <briantist> hi I'm gonna try to join this one... but high chance I get pulled away or distracted
15:02:50 <sutapa_b[m]> hi
15:02:55 <oranod> hey. o/ I'm around but double booked so response times vary...
15:03:07 <samccann> #chair sutapa_b briantist Don Naro
15:03:07 <zodbot> Current chairs: Don Naro briantist samccann sutapa_b
15:03:10 <samccann> welcome welcome!
15:03:45 <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:04:02 <samccann> #info official agenda at https://github.com/ansible/community/issues/678#issuecomment-1503847572
15:04:03 <samccann> #topic Action Items
15:04:19 <samccann> #info open @oraNod to review open issues on docsite and mark some easyfix or worth highlighting in this channel
15:05:10 <samccann> all issues are here now, right? -https://github.com/ansible/docsite/issues
15:05:18 <oranod> hey I did go through the docsite issues and transferred a bunch from the jinja-docsite
15:05:36 <samccann> ok cool!
15:05:41 <acozine> o/
15:05:46 <oranod> I'll create an easy fix label or something. please do nag me.
15:05:53 <samccann> :-)
15:06:00 <samccann> #chair acozine
15:06:00 <zodbot> Current chairs: Don Naro acozine briantist samccann sutapa_b
15:06:03 <acozine> I need fresh tea and a jacket or sweater or something
15:06:04 <acozine> BRB
15:06:28 <samccann> tea and a sweater for cozy docs meetings!
15:07:18 <samccann> #info closed  @samccann to create tracking issues on awx operator docs effort https://github.com/ansible/awx-operator/issues/1356
15:07:30 <samccann> #topic Documentation Updates
15:07:55 <samccann> #info have multiple requests coming in for help with docs across various ansible projects and collection(s)
15:08:37 <samccann> ^^ kind of exciting actually. So we have the awx operator which is in full swing now. And a request for collection docs. Once we settle on the details, we'll be asking for help on that as well
15:09:14 <samccann> #info these are smaller projects so good candidates for people who want to get a start-to-end project under their belts in docs land
15:10:04 <samccann> sutapa_b: did you have any comments/questions on the mkdocs stuff you're setting up for awx operator?
15:11:07 * acozine reads the backscroll
15:11:27 <samccann> heh
15:12:36 <sutapa_b[m]> So I have some observation like doing 'pip install mkdocs' didn't actually let me run mkdocs commands on terminal. I had to do 'apt install mkdocs' and such. But I can probably put them aside later.
15:13:01 <sutapa_b[m]> Right now I will do the suggestion that you recommended so that mkdocs.yaml works on the project.
15:13:13 <samccann> so I seem to recall there were two options on that
15:13:16 <samccann> 1. create index.md
15:13:28 <samccann> 2. just add files to the nav section of mkdocs.yml
15:14:11 <samccann> Don Naro: do you know if there's a preference for one vs the other approach? I'd guess this operator will have maybe 2 guides with 3+ files each (random guess)
15:15:41 <oranod> I'm not really sure tbh. ssbarnea might be the best person to ask about mkdocs.
15:15:42 <felixfontein> o/
15:15:51 <oranod> aloha felixfontein
15:16:13 <samccann> as for the apt install etc, I think I have an example of a requirements.txt file that basically has the pip install for everything. I'll pop that in a comment in the PR sutapa_b
15:16:25 <samccann> #chair felixfontein
15:16:25 <zodbot> Current chairs: Don Naro acozine briantist felixfontein samccann sutapa_b
15:16:26 <samccann> welcome welcom
15:17:25 <acozine> we've got a good bunch of DaWGs assembled today!
15:17:29 <samccann> \o/
15:17:53 <samccann> #info Need help on  collection dependencies docs issue - https://github.com/ansible/ansible/issues/80435
15:18:02 <samccann> I just noticed that one before the meeting
15:18:25 <samccann> A quick scan (didn't read all the details yet) but made me wonder if -
15:18:42 <samccann> 1- it's already covered somewhere else? our collection developer/contributor docs are still scattered
15:18:57 <samccann> 2 - Is it something that needs discussion (community-topic)?
15:19:08 <samccann> If y'all can take a quick look and let me know what you think
15:20:55 <felixfontein> that's a discussion for community-topics I think
15:21:02 <acozine> Hm, it looks like this ticket says "As a collection developer, I want a standardized way to tell collection users what dependencies they need to install on their Ansible controller before they can use my collection" - is that a good summary?
15:21:07 <felixfontein> russoz and me were discussing this already at some point for community.general
15:21:21 <acozine> so it's part documentation, part not documentaiton
15:21:25 <samccann> ok I can copy the long description and put it into a community topic
15:21:41 <felixfontein> it's - as usual - complicated ;)
15:21:56 <samccann> heehee
15:22:02 <acozine> first we need to agree on the best way to describe/list dependencies, then we need to document what we agreed?
15:22:52 <samccann> sounds about right to me
15:23:26 <samccann> #action samccann to create community-topic to discuss  https://github.com/ansible/ansible/issues/80435
15:23:43 <acozine> heh, I misread the label, it actually says `affects_2.16` but I read `affects_2.6` and I thought, "Wow, that was before collections even existed!
15:23:54 * acozine needs more caffeine
15:25:07 <samccann> hah! yep
15:25:17 <samccann> #info looking for help on creating a cheatsheet for ansible commands - https://github.com/ansible/ansible/issues/75509
15:25:41 <samccann> acozine kindly added our first one, but we could use help creating a similar section for the other common Ansible commands
15:26:43 <acozine> ooh, that's a good one
15:27:01 <samccann> yeah I think it would be helpful if we can get the rest of the commands there
15:27:19 <acozine> the page is https://docs.ansible.com/ansible/latest/command_guide/cheatsheet.html
15:27:56 <samccann> This is what the playbook one looks like - https://docs.ansible.com/ansible/latest/command_guide/cheatsheet.html
15:28:33 <samccann> so on the one hand, seems almost an 'easyfix' for someone who knows ansible.  Do you  think I should label it that and see what happens? or am I delusional?
15:28:56 <acozine> someone put a note on the issue last fall saying they could help
15:29:17 <acozine> the easyfix thing might be worth a try
15:30:22 <samccann> gah! didn't even notice that comment! pinged them to see if they are still up for it and I'll add easyfix and see what happens
15:30:55 <acozine> even without much ansible experience, it might be fairly easy - we already have comprehensive documentation of the CLI commands, it's just not presented in the most user-friendly way
15:31:24 <acozine> compare https://docs.ansible.com/ansible/latest/cli/ansible-playbook.html#ansible-playbook to https://docs.ansible.com/ansible/latest/command_guide/cheatsheet.html
15:32:33 <acozine> the main CLI documentation describes a lot more options, too
15:33:05 <samccann> coolness
15:33:27 <samccann> #info Ansible 8 alpha docs up on test at http://docs.testing.ansible.com/ansible/8/index.html  Please review and let us know if you see problems.
15:34:14 <samccann> #topic doc tools
15:34:43 <samccann> felixfontein: Don Naro any updates in this area?
15:35:20 <samccann> We are kind of in a mini-freeze so to speak since things like antsibull-docs live in core and core 2.15 is in freeze until the release etc
15:36:26 <felixfontein> I started creating PRs for semantic markup support for other projects, but nothing really happened yet - I also wasn't able to test the most interesting ones (i.e. Automation Hub UI and Ansible Language Server) since I didn't have time to try to figure out how to set them up...
15:37:12 <samccann> thanks for continuing that effort on the other projects!
15:37:47 <oranod> apologies for the delay. just got out of the other meeting I was in and taking my attention.
15:38:31 <oranod> #info we've added some "quicklinks" to the new docsite layout. you can find them on the index, user, developer, and maintainer pages. currently on the preview site at: https://ansible.github.io/jinja-docsite/
15:39:14 <oranod> if anyone has thoughts on those links or better suggestions, I'd appreciate your feedback
15:39:44 <samccann> at what point do we move that to docs.ansible.com?
15:40:44 <oranod> good question. I see no reason to wait but would like to merge the other two PRs that alphabetize the ecosystem page and add edge to the ecosystem.
15:41:07 <oranod> so as soon as those other two PRs are merged, I'll send a PR to update docs.ansible.com
15:42:18 <oranod> oh, I should also ping gotmax about the quicklinks and see what he thinks. and I'm sure we'll get more feedback after the quicklinks go live but wanted to take the opportunity to highlight them on the staging site and allow time for feedback.
15:42:19 <samccann> sounds great thanks!
15:42:48 <acozine> woopsie, outage report
15:42:56 <samccann> fun times!
15:42:57 <acozine> I need to drop off, sorry
15:42:59 <acozine> heh
15:43:00 <felixfontein> good luck acozine!
15:43:06 <acozine> thanks!
15:43:10 <samccann> #topic Open Floor
15:43:33 <samccann> Here's the time to bring up anything docs related! Got a burning question/pr/issue? A new idea?
15:43:43 <samccann> ..an old idea we forgot about?  :-)
15:45:10 <samccann> ...a fav. pizza topic to tell Don to add to his family pizza night??
15:45:11 <felixfontein> realistic ones, or unrealistic ones? ;)
15:45:41 <oranod> I'm always open to pizza recipes, realistic or not
15:45:42 <samccann> hey semantic markup seemed unrealistic for 2+ years but now it's reality so.. go for it!
15:47:33 <samccann> ok things have gotten quiet so I guess don's on his own for pizza ideas! About to end meeting unless someone screams
15:48:02 <felixfontein> what if someone screams 'STOP THE MEETING!'?
15:48:09 <samccann> STOP THE MEETING!!
15:48:17 <samccann> DON NEEDS MORE PEPPERONI!!!
15:48:18 <samccann> heh
15:48:39 * samccann amused that will all live in meeting logs for the next decade
15:48:46 <samccann> #endmeeting