15:02:10 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:02:10 <zodbot> Meeting started Tue May 30 15:02:10 2023 UTC.
15:02:10 <zodbot> This meeting is logged and archived in a public location.
15:02:10 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:02:10 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:02:10 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:15 <acozine> o/
15:02:18 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:26 <acozine> pass me my party hat!
15:02:30 <samccann> #chair acozine
15:02:30 <zodbot> Current chairs: acozine samccann
15:02:31 <samccann> hehe
15:02:32 <TVo[m]> Hello all o/
15:02:36 <sutapa_b[m]> o/
15:02:40 <acozine> hi TVo !
15:02:45 <samccann> #chair TVo  sutapa_b
15:02:45 <zodbot> Current chairs: TVo acozine samccann sutapa_b
15:02:48 <samccann> welcome welcome!!!
15:02:50 <acozine> hi sutapa_b
15:03:08 <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:03:17 <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:03:25 <oranod> o/
15:03:30 <oranod> hi all!
15:03:43 <sutapa_b[m]> acozine: hi 😃😃
15:04:08 <samccann> #chair Don Naro
15:04:08 <zodbot> Current chairs: Don Naro TVo acozine samccann sutapa_b
15:04:16 <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:24 <samccann> #info official agenda at https://github.com/ansible/community/issues/678#issuecomment-1563022811
15:04:31 <acozine> hi Don Naro
15:05:35 <samccann> Last week (thanks to felixfontein ) we learned the script we use to summarize meeting minutes requires using the #topic command at least once!  So now I added some 'how to run the meeting' to the top of the weekly agenda in case Don or I aren't around and someone else pops in to run them!
15:05:53 <acozine> ah, good to know
15:06:04 <samccann> yeah I hadn't a clue either!
15:06:22 <samccann> but it's all happily documented now so... smooooth sailing!
15:06:48 <samccann> meanwhile if we had any action items, I entirely lost track so... clean slate to start the 2nd half of the year!
15:07:06 <samccann> #topic Documentation Updates
15:07:16 <samccann> #info Ansible 8 will be released today! Docs release prep in the works as well.
15:07:34 <samccann> #info ansible-core 2.12 is EOL... will update the docs accordingly this week
15:07:43 <samccann> and the ansible train moves forward!
15:08:08 <samccann> #topic Execution Environments
15:08:19 <samccann> This one got busy in the last couple of weeks.
15:08:30 <samccann> #info ansible-builder 3.0 is out and needs new/updated docs
15:08:50 <samccann> #info andersson007_ is leading the effort and drafting out some of this
15:09:03 <samccann> #info see https://github.com/ansible-community/community-team/issues/230 to help out
15:09:10 <felixfontein> sorry, I don't really have time today :)
15:09:23 <samccann> no worries just thanking you for last week's meeting minutes help!
15:09:38 <oranod> #info there is also this PR where folks can help with documenting the ENV ANSIBLE_GALAXY_SERVER_* vars: https://github.com/ansible/ansible-builder/pull/538
15:09:41 <acozine> andersson007_: I've got drafts of docs based on a conversation with nitz
15:09:44 <oranod> hi felixfontein
15:09:48 <acozine> (docs for ansible-buidler)
15:10:08 <acozine> hi/bye felixfontein
15:10:38 <samccann> acozine: can you add that to the epic? Andrei isn't able to make these meetings so using the issue is probably the best place to coordinate
15:10:45 <acozine> sure
15:11:10 <acozine> my plan is to contribute a PR to the ansible-builder repo, then coordinate with Andrei from there
15:11:56 <samccann> yeah that's my big question on all of this. right now the only community docs are in builder.. which is the.. ahem.. .building tool to create EEs.
15:12:42 <samccann> We don't have a 'home' for how to USE EEs. And I'm wondering from those more in the know - should we have how to use EEs in the builder docs themselves or somewhere else? I know they exist in the ansible-controller docs, but that's downstream right now
15:12:55 <samccann> TVo: - do you have thoughts?
15:13:10 <acozine> EEs can be used in other contexts, not just in Controller/AWX
15:13:29 <samccann> yeah that's what I thought. but we don't have a 'home' for that sort of docs yet.
15:13:38 <oranod> we talked about having the How To's that span projects in the ecosystem as part of the package docs. does that make sense?
15:13:48 <samccann> we've basically slammed things like that into ansible/ansible in the past but don't want to continue that
15:14:15 <samccann> Thanks Don Naro that helps.
15:14:48 <samccann> But also feels like we need Deep Thoughts(tm) about this new category of 'ecosystem docs' so to speak. Or it's a hodgepoge of cross-project docs.
15:15:15 <samccann> i'm flying blind here because I haven't read any of the EE details etc, but thinking it won't be the only 'guide' that spans projects going forward?
15:15:58 <oranod> right, hopefully we can identify a few more of these cross-project journeys and create additional doc contribution opportunities
15:16:12 <acozine> the builder docs don't belong in ansible/ansible
15:16:31 <acozine> but I'm not sure where they do belong
15:16:48 <oranod> no, builder docs don't belong in ansible/ansible but the EE guide shouldn't be entirely builder specific
15:17:37 <oranod> the How Tos are a little different in that they span projects, which some folks on the builder team have said don't belong in the builder docs
15:17:40 <samccann> yeah it feels like a new 'space' so to speak
15:18:01 <TVo[m]> I have this chapter in the controller docs for how to use EEs in JTs: https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html
15:18:27 <samccann> thanks TVo  - do you know if AWX has a section like that as well?
15:19:24 <samccann> #info these EE docs are a new 'category' in that the how to guide will span more than one Ansible community project (builder, AWX, stand-alone use, etc)
15:19:38 <samccann> hmm they work with ansible-navigator as well, right?
15:19:45 <oranod> yarp
15:20:14 <samccann> ok so the Deep Thoughts, for those interested, would be thinking about where we put multi-project documentation.
15:20:56 <samccann> And how we display it on the docsite. As Don mentioned, we have the ecosystem page that lists all the multiple ansible projects. So maybe that page also links to 'cross-project guides'... urf.. which sounds like a vague and painful name but anyway
15:21:01 <TVo[m]> Yes I believe AWX has similar content
15:21:31 <samccann> #info AWX might have similar content to controller on using EEs in job templates - https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html
15:21:36 <samccann> ...just so's we don't forget
15:21:50 <TVo[m]> https://github.com/ansible/awx/blob/devel/docs/execution_environments.md
15:21:58 <samccann> oh cool!
15:21:59 <TVo[m]> I am not sure how up-to-date this is though
15:22:03 <samccann> #undo
15:22:03 <zodbot> Removing item from minutes: <MeetBot.items.Link object at 0x7f1e014389e8>
15:22:36 <samccann> #info controller has https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html and AWX has https://github.com/ansible/awx/blob/devel/docs/execution_environments.md for EEs in job templates (tho the latter may not be up-to-date)
15:22:50 <samccann> #info and in general, most docs are not up todate with Builder 3.0
15:23:38 <samccann> so we need to update docs to use builder 3.0, and figure out what we do with these cross-project docs etc. All help welcome at https://github.com/ansible-community/community-team/issues/230
15:24:15 <samccann> This is also a good place for any technical writers to help out with as the main authors will be developers who could use some information architecture and editorial help along the way!
15:24:35 <samccann> #action samccann to inform community-writers about EE epic for a place to help out
15:25:33 <samccann> anything else we should chat about wrt EEs today? any obvious next steps etc?
15:26:13 <acozine> I'll try to get a PR open this week as a starting point for discussion next week.
15:26:42 <samccann> cool thanks!
15:27:36 <samccann> potentially related? is ...
15:27:44 <samccann> #info Need help on  collection dependencies docs issue - https://github.com/ansible/ansible/issues/80435 and https://github.com/ansible-community/community-topics/issues/224
15:28:43 <samccann> only because someone metioned in the first issue that this is an EE problem to solve so to speak? Not sure where either is going at the moment so perhaps someone more in the know can take a look at least at the ansible/ansible issue to see if it should be closed in favor of ..wherever the community topic (and EE docs) are going
15:29:39 <samccann> #topic Ansible command cheatsheet
15:29:51 <samccann> #info looking for help on creating a cheatsheet for ansible commands - https://github.com/ansible/ansible/issues/75509
15:30:59 <samccann> so TL;DR; - we want a good 'sample' command per ansible cli command that uses the most common flags. and then we describe what each flag is doing
15:31:19 <samccann> I had a 'thought' the other day - could we open this up to either a community-topic or reddit or someting?
15:31:28 <samccann> s/someting/something
15:32:05 <samccann> Right now we have writers who want to help, but not the knowledge on what are good flags etc. So if we got technical folk involved, we could get the most commonly used flags decision made so to speak
15:32:12 <samccann> or maybe not 'decision' but at least feedback?
15:32:26 <acozine> that sounds like a great idea
15:32:53 <acozine> ask folks "how do you use this command-line tool?"
15:33:02 <acozine> and see what the most common flags are
15:33:10 <acozine> from actual users
15:33:19 <samccann> cool cool
15:33:41 <samccann> #action samccan to ask on reddit 'how do you use this cli command' type questions for feedback
15:34:24 <samccann> any volunteers to ask a similar question (or set of questions) at  https://github.com/ansible-community/community-topics/issues ?
15:35:12 <samccann> I could potentially ask one of the community-writers to ask the question if no one here is interested. It's a good way to get more deeply involved in Ansible so to speak
15:35:20 <samccann> good and relatively easy ;-)
15:35:52 <samccann> and I can work with whomever asks the question on how to pose it etc
15:36:31 <sutapa_b[m]> Is this about asking about the options to be used in the cheat sheet?
15:36:37 <samccann> yep
15:36:45 <sutapa_b[m]> I can do that
15:36:52 <samccann> cool thanks!
15:37:05 <samccann> we can chat about it right after this meeting if you have time or another day
15:37:33 <sutapa_b[m]> sure right after
15:37:37 <samccann> coolness!
15:37:52 <samccann> #topic Ansible 8 release
15:37:59 <samccann> should have posted this earlier, but anyway
15:38:07 <samccann> #info Ansible 8  docs up on test at http://docs.testing.ansible.com/ansible/8/index.html  Please review and let us know if you see problems. Ignore version switcher as those PRs still need to be backported etc
15:38:36 <samccann> oh sorry that should be http://docs.testing.ansible.com/ansible/latest/index.html
15:38:41 <acozine> congrats on getting the 8.x docs out!
15:38:56 <samccann> I'm still fiddling with the version checker but that's the actual docs that will be published later today!
15:39:19 <samccann> #info major kudos to oranod for getting ansible-core 2.15 docs published and the prep work for Ansible 8
15:39:27 <samccann> cuz he's done most of this in May!
15:39:47 <samccann> #topic Doc tools and docsite
15:40:00 <samccann> Any updates in this area?
15:40:28 <samccann> I know there's a translation page PR waiting for review https://github.com/ansible/jinja-docsite/pull/107
15:40:53 <samccann> I haven't tried it out locally yet and I think that's still the only way to 'see' these PRs right?
15:40:55 <TVo[m]> I started reviewing but had to hop on a call
15:41:03 <TVo[m]> Can you add Yanis as a reviewer?
15:41:07 <oranod> I also created an issue last week if anyone wants to help out and take a chunk of the jinja templating improvements
15:41:40 <oranod> #info here is the link with details if anyone wants to contribute to improving the jinja templates for the docsite: https://github.com/ansible/jinja-docsite/issues/108
15:41:49 <samccann> TVo: just added him, thanks!
15:42:48 <oranod> I'm thinking about maybe using Read The Docs to get PR previews for the docsite and replace GH pages
15:44:07 <oranod> samccann: I also created a draft issue in the writer's board here: https://github.com/orgs/ansible-community/projects/3/views/1?layout=board
15:44:09 <oranod> is that OK?
15:44:42 <samccann> that's changing the layout of the board itself?
15:44:44 <oranod> that way it links the issue in the jinja-docsite repo to the writer's board so anyone looking there can see there is a ticket open
15:45:12 <oranod> not changing the layout, just creating an issue on the board that links to the docsite issue
15:45:49 <samccann> this is what I see at that link
15:45:53 * samccann uploaded an image: (139KiB) < https://libera.ems.host/_matrix/media/v3/download/ansible.im/ea89a1d5e6514a777be132afc0f644bce8d7d117/image.png >
15:46:09 <samccann> which is just basically changing the layout. I don't see a jinja2 docsite issue there?
15:46:31 <oranod> ah OK. it's because I have it saved as a draft and need to convert it to an issue
15:46:32 <samccann> oooh I see it at the bottom
15:46:57 * samccann uploaded an image: (91KiB) < https://libera.ems.host/_matrix/media/v3/download/ansible.im/b4050aa4d9310f22c676ce3b4fddb32cb99ccb59/image.png >
15:47:23 <samccann> lemme open a topic here
15:47:33 <samccann> #topic Adding to the community-writers project board
15:48:05 <samccann> #info this board is for community members interested in growing their writing skills or technical writers interested in helping with ansible docs
15:48:35 <samccann> #info two main categories of issues - those that can be fixed with Edit on Github, or those that require git knowledge
15:48:46 <samccann> #info you can also post a PR for techwriter review there
15:49:10 <samccann> #info copy a link from your issue or PR and add it to the board
15:49:46 <samccann> So in general don, if you have an issue for that, just copypasta into the board and it'll show up. Then lemme know so I can set the fields appropriately if they aren't logical on their own etc
15:49:59 <samccann> figured it was worth getting that into the meeting minutes
15:50:25 <oranod> yeah it's good to get that into the minutes
15:50:26 <oranod> thanks
15:50:35 <oranod> I just converted my draft to an issue so it should be there
15:50:52 <samccann> cool yep i see it now, thanks!
15:51:33 <oranod> rocking. I'll point some other people to that board too, like Abhijeet. he was asking about getting some community writers into the builder docs as I mentioned earlier.
15:52:02 <samccann> yep cool. Just keep in mind and let him know the skillset is quite varied
15:52:21 <samccann> most of what gets fixed are easyfix items with a lot of detail on exactly what to fix in the isue
15:52:24 <oranod> what do you think about putting some other issues there for the likes of the AWX Operator?
15:52:27 <samccann> issue even.. can't type today
15:53:16 <samccann> I've lost track of AWX operator at the moment but we did have a community-writer break apart the readme into multiple files and I think theres some strange error on the PR to set up the mkdocs build right?
15:53:44 <oranod> yeah I pinged Hao about that error last week. need to look at that again...
15:54:13 <samccann> yeah so I think once we get to the point where they are published to RTD, we can then ask more community-writers to come in and clean up etc
15:54:26 <samccann> I just don't want to toss newish writers onto something that isn't quite working yet
15:54:50 <samccann> but then we have ..at least one other operator needing the ssame work, and maybe something in EDA land? I have notes 'somewhere' but can't recall
15:54:57 <oranod> I also wanted to point some other folks at that board so they can find issues - is that board just for the WTD community writers?
15:55:11 <samccann> in general, at least two more projects like AWX operator
15:55:24 <samccann> No the board is just for writers in general
15:55:48 <samccann> Tho we'd have to add new names to the assigment list if other writers are interested. Easy enuf to do
15:56:12 <samccann> but the gist of it is, a writer assigns the issue to themselves in the dropdown box on that page so other's know someone has taken it
15:56:27 <samccann> #info  a writer assigns the issue to themselves in the dropdown box on that page so other's know someone has taken it
15:56:50 <oranod> hmm. maybe I should break that into multiple issues then...
15:57:26 <samccann> They currrent batch of WTD writers are on discord so you or I can ask if any have HTML skills and want to help
15:57:39 <samccann> if they have the skills, they may not need smaller issues etc..
15:57:53 <samccann> ooch.. need to do a quick open floor
15:57:58 <samccann> #topic Open Floor
15:58:08 <bcoca> smaller issues are directly proportional to the conservation of sanity
15:58:09 <samccann> Anyone have anything docs-related to discuss or bring up? here's the time!
15:58:15 <samccann> and sorry to sqeeze it in the end
15:58:17 <acozine> I have to run to #nextmeeting
15:58:20 <samccann> hehe true
15:58:23 <samccann> thanks acozine!
15:58:34 <samccann> smaller issues have a better chance of getting fixed as well
15:58:46 <bcoca> one thing i might need to open issue, docsbuild does not look at symlinks as aliases and lists them as real plugins (systemd vs systemd_services)
15:58:47 <oranod> bye acozine
15:58:49 <bcoca> one is alias of the other
15:58:54 * acozine waves
15:59:07 <samccann> lol
15:59:21 <TVo[m]> I have to drop off too. Bye all
15:59:28 <oranod> see you TVo !
15:59:33 <samccann> ok seems a natural end then
15:59:34 <samccann> #endmeeting