15:01:19 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:19 <zodbot> Meeting started Tue Apr 25 15:01:19 2023 UTC.
15:01:19 <zodbot> This meeting is logged and archived in a public location.
15:01:19 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:19 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:19 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:31 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:41 <samccann> Welcome Pelisse Romain !!
15:01:43 <PelisseRomain[m]> Me :)
15:01:50 <samccann> #chair Pelisse Romain
15:01:50 <zodbot> Current chairs: Pelisse Romain samccann
15:02:00 <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:01 <oranod> welcome Pelisse Romain
15:02:05 <oranod> o/
15:02:10 <samccann> #chair Don Naro
15:02:10 <zodbot> Current chairs: Don Naro Pelisse Romain samccann
15:02:16 <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:27 <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> #info official agenda at https://github.com/ansible/community/issues/678#issuecomment-1513422458
15:03:43 <samccann> #topic Action Items
15:03:53 <samccann> #info open @oraNod to review open issues on docsite and mark some easyfix or worth highlighting in this channel
15:04:00 <samccann> any progress? ^^
15:05:13 <acozine> o/
15:05:44 <samccann> #chair acozine
15:05:44 <zodbot> Current chairs: Don Naro Pelisse Romain acozine samccann
15:05:47 <samccann> welcome welcome
15:06:00 <acozine> hello docs folks!
15:06:02 <anwesha[m]> Hello everyone
15:06:11 <oranod> sort of... I have gone through them and identified a few gaps and some other work items that I need to break into issues.
15:06:14 <samccann> #chair anwesha
15:06:14 <zodbot> Current chairs: Don Naro Pelisse Romain acozine anwesha samccann
15:06:17 <samccann> welcome as well!
15:06:26 <oranod> don't have a sparkling/shiny list right now though 😦
15:06:33 <oranod> hi acozine and anwesha
15:06:34 <samccann> cool thanks for continuing on that Don Naro ~
15:07:09 <samccann> yeah takes time to get the backlog reviewed, add new issues, and find things that might be easy for a first  time contributor.
15:07:25 <samccann> #topic Documentation updates
15:07:58 <samccann> Pelisse Romain: since you're here, did you want to go over the docs issue for your.. erm.. collection I think it is?
15:08:26 <PelisseRomain[m]> Yep, I was waiting for you guys to let me know when was the appropriate time :)
15:08:35 <PelisseRomain[m]> So, a bit of context first.
15:09:13 <PelisseRomain[m]> We produced a bunch of collections as part of an initiative dedicated to provide better Ansible integration for the Middleware (now called Runtimes) solution of Red Hat.
15:09:54 <PelisseRomain[m]> Those includes Wildfly (product name EAP), Infinispan (product name JDG), Tomcat (product name: JWS) and some others
15:10:17 <oranod> Infinispan++ 🚀
15:10:39 * samccann thinks don might be biased... ;-)
15:11:02 <PelisseRomain[m]> I think we did a fair job, from a technical point of view, and we are happy about the features we have implemented, but we did not really put any thoughts in the documentation
15:11:38 <PelisseRomain[m]> We generally have a basic README and we, of course, prodives all the info Ansible lint and Molecule requires to be happy with us, but that's all.
15:12:00 <PelisseRomain[m]> (one can biased and right at the same time ;) )
15:12:06 <samccann> hehe
15:12:09 <PelisseRomain[m]> So, in short
15:12:35 <PelisseRomain[m]> from a documentation point of view, I think those collections can be used for any volunteer here as a playground
15:12:58 <PelisseRomain[m]> Look at them, and if you see something you don't like, you feel can be reorganized, etc...
15:13:04 <PelisseRomain[m]> Feel free to submit a PR.
15:13:19 <oranod> https://github.com/ansible-middleware
15:13:49 <PelisseRomain[m]> Thanks about do that (should we put some sort of command in front of the link?)
15:13:51 <acozine> how easy is it to spin up instances of the projects this collections documents? If someone wanted to test the Ansible functionality against the open-source version, how easy/hard would that be?
15:14:16 <samccann> I thought I opened an issue for the wildfly but can't find it now?
15:14:33 <acozine> it's a lot easier to write good docs if you test them as you go
15:15:08 <PelisseRomain[m]> acozine: it's pretty easy, all (upstream) collection are using the (upstream) product. So you just need to run the default playbook, it will download and install the associated product.
15:15:09 <oranod> samccann: https://github.com/ansible-middleware/wildfly/issues/105
15:15:14 <acozine> awesome
15:15:28 <PelisseRomain[m]> Ex: If you install middleware_automation.wildfly, it's going to install Wildfly.
15:15:44 <samccann> #info looking for docs help for wildfly collection - https://github.com/ansible-middleware/wildfly/issues/105
15:16:03 <PelisseRomain[m]> So this issue might have been a bad idea on my behalf
15:16:30 <PelisseRomain[m]> I wanted you guys to have some info, beyond what's in our documentation, so I provided some blog articles I've wrote
15:16:45 <samccann> The blog articles help.
15:17:06 <PelisseRomain[m]> However, the issue somehow mutated into "how to add blog content" to the documentation (which is not a bad idea, but a **subset** of my original inquiry.
15:17:27 <samccann> :-)
15:18:05 <samccann> so the general ask is to look at the existing readme files and clean them up/make them clearer?
15:18:15 <samccann> and then consider adding some of the details from the blog posts?
15:19:00 <PelisseRomain[m]> samccann: exactly! First, look at anything you feel is wrong/bad/could be done better and submit changes (via PR)
15:19:24 <PelisseRomain[m]> Then have a look at the articles and do a comparaison ("oh, this thing in the article is important, it should be there in the documentation")
15:19:47 <oranod> something I think might be missing here is a central place where contributors can easily find work items.
15:20:12 <oranod> hey domi.vagner !
15:20:40 <PelisseRomain[m]> I would use the Github issues of each collection.
15:20:47 <acozine> The current README has a lot of great information. It looks like it's a mix of info for users and info for developers.
15:21:27 <samccann> #info initial request for help is to review/edit existing readme files to clarify etc. Then can consider adding content from the blog posts into the readme where appropriate
15:21:45 <PelisseRomain[m]> I don't to create a bunch of issues, but I would say if (for example) samccann is up to review the documentation of the Wildlfy collection, samccann can create an issue called "Review the documentation" assign it to them and then use this issue when filling PR.
15:21:52 <PelisseRomain[m]> * I don't want to create
15:22:25 <PelisseRomain[m]> Then we can use the issue to discuss (when the discussion cannot live on PR or simply if the volunteer has some question)
15:25:41 <oranod> Pelisse Romain: what if we added a page to https://ansiblemiddleware.com/# like "Get involved" that explains how to contribute to the docs. I think my point from before is that there are separate repos for each collection. and that page would be easy to put in the Bullhorn (Ansible newsletter) to call for contributors.
15:26:12 <PelisseRomain[m]> I did not know you could do that, but yes, gladly! Would someone here volunteer to draft this page?
15:26:34 <oranod> if no one else raises their hand I can do it
15:26:56 <oranod> and remind me to explain how to submit to the Bullhorn Pelisse Romain
15:26:57 <PelisseRomain[m]> That'll be great :)
15:27:13 <PelisseRomain[m]> oranod: That'll be great too :)
15:27:56 <samccann> cool thanks Don Naro
15:29:21 <samccann> I admit I don't have much for agenda items today
15:29:56 <samccann> it looks like this one on python compatibility in collection docs was discussed at the community WG - https://github.com/ansible-community/community-topics/issues/224
15:30:03 <samccann> but I haven't had a chance to read the logs.
15:32:17 <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:33:12 <samccann> #info looking for help on creating a cheatsheet for ansible commands - https://github.com/ansible/ansible/issues/75509
15:33:32 <samccann> I think it might be worth turning that specific issue into a bullhorn call for help? What do y'all think?
15:33:48 <acozine> yeah, that sounds like a good idea
15:33:48 <samccann> seems like people who know/use the commands every day could pick that up and add one or two commands?
15:34:44 <acozine> even if you don't use the commands every day, you can look at the CLI docs and construct a cheatsheet, as long as you have some sense of what would be common flags
15:35:06 <acozine> the cheatsheet is basically a set of annotated examples for the CLI docs
15:35:38 <acozine> the CLI docs are comprehensive, they just don't show you examples
15:35:57 <samccann> how about this -
15:35:58 <samccann> Do you know your Ansible CLI commands inside and out? How about adding a good sample command with common flags to the Ansible cheatsheet to help our your fellow Ansible users! See https://github.com/ansible/ansible/issues/75509 and the linked PR for an example. We need your help getting a full set of sample commands!
15:36:52 <acozine> that sounds great - I'd add al ink to the CLI docs too
15:37:33 <samccann> I'll add it to the issue if it's not already there, thanks!
15:37:58 <acozine> https://docs.ansible.com/ansible/latest/command_guide/command_line_tools.html
15:38:51 <samccann> yep you added it as a comment already !
15:38:59 <samccann> #topic Open Floor
15:39:12 <acozine> heh
15:39:13 <samccann> I'm flaffing about now. Anyone have docs ideas/issues/PRs to talk about?
15:39:16 <acozine> at least I'm consistent
15:39:25 <samccann> :-)
15:41:48 <oranod> #info we've migrated Ansible Sign docs over to readthedocs and trying to get Galaxy to RTD as well in the next couple of weeks. that will mean all active projects in the ecosystem will be hosted on RTD (another step towards consistent ecosystem)
15:42:11 <oranod> I'll throw a few info items in here if anyone has questions or comments, fire away
15:42:26 <oranod> thought the RTD thing is worth mentioning
15:42:40 <samccann> cool thanks!
15:42:40 <acozine> what "RTD thing"?
15:42:56 <acozine> ah, nm
15:42:59 * acozine reads the backscroll
15:43:29 <samccann> RTD = Read The Docs - a hosting option where most other Ansible projects publish there docs (for those not familiar)
15:43:56 <acozine> does Ansible have an org there or something similar?
15:44:12 <acozine> someplace people can go and see all the ansible-related docs that get published there?
15:44:18 <oranod> we're moving towards having an org there but it's not up yet
15:47:07 <oranod> #info the ecosystem page is updated to include edge and is now in alphabetical order too, which hopefully helps with navigation https://docs.ansible.com/ecosystem.html
15:47:52 <bcoca> most docs in readthedocs were from tools developed by 3rd parties (that later were integrated into ansible project )
15:48:22 <acozine> huzzah for alphabetizing!
15:48:41 <samccann> bcoca - it's kind of the 'first choice' now for a number of other Ansible projects as well.
15:48:55 <PelisseRomain[m]> <samccann> "RTD = Read The Docs - a hosting..." <- I'm not sure if we post our documentation there (for our collection)... Should we look into this?
15:49:38 <samccann> The individual collection is fine wherever you publish
15:50:10 <samccann> We aren't going to create a separate index for all the collections etc. That should be what Galaxy (NG) does for collections not already in the package
15:52:11 <samccann> just did a quick check on the # of visitors choosing to switch over to the old docsite.. we are down from 3% to 1.6% !!
15:52:32 <samccann> thanks to Don adding quicklinks imo last week. I forget what day tho
15:52:46 <oranod> I forgot that was last week lol
15:52:59 <oranod> feels like a month ago now
15:53:26 <oranod> but that's positive news 📉
15:54:06 <oranod> #info the docsite journeys have been updated to reflect some of the changes we made while building out the docs.ansible.com pages. https://github.com/ansible/docsite/blob/main/data/journeys/docsite-journeys.md
15:54:06 <samccann> yep. if I do it for just the last few days, we are down to 1.1%
15:54:06 <samccann> so calling that a big win!
15:55:18 <oranod> I wanted to mention this one about the docsite journeys as well, especially to keep a bit of focus on them and maybe explore how we can go about expanding them and identifying new journeys that extend into the ecosystem
15:56:03 <samccann> yeah that's a good idea. We here tend to know the core/collection journeys but not necessarily what drives users/contributors toward all the other ansible projects
15:56:18 <oranod> a really interesting one is community ee's
15:58:06 <samccann> for sure! Loads of work to do there for docs as well
15:58:15 <samccann> We're nearing the top of the hr. Any last minute thoughts before we end?
15:59:28 <PelisseRomain[m]> it was fun :) thanks for inviting me :)
15:59:55 <samccann> always welcome! we have (virtual) 🍪 !
16:00:12 <oranod> great to see you around these parts Pelisse Romain welcome, welcome
16:00:27 <oranod> you too domi.vagner a very warm welcome
16:01:12 <samccann> #endmeeting