16:00:03 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:00:03 <zodbot> Meeting started Tue Jan 18 16:00:03 2022 UTC.
16:00:03 <zodbot> This meeting is logged and archived in a public location.
16:00:03 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:00:03 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:00:03 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:00:09 <samccann> #topic opening chatter
16:00:21 <samccann> @room who's up for talking docs today?
16:00:26 <gundalow> o/ (half here)
16:00:38 <gundalow> 31 hour for alert sounds like a cool idea
16:00:42 <samccann> #chair gundalow bcoca
16:00:42 <zodbot> Current chairs: bcoca gundalow samccann
16:01:01 <samccann> #action samccann to change room alert to 31 hrs for help wanted nag
16:01:21 <samccann> Raise your asciidoc hand (o/) say hi or any other way you want to let us know you are here.
16:01:34 <samccann> oof.. writerness showing there... meant ascii hand lol
16:01:35 <briantist> o/
16:02:00 <felixfontein> o/
16:02:31 <felixfontein> bcoca: any two *different* primes :P
16:02:33 <samccann> andersson007_tadeboro cyberpear up for chatting docs today?
16:02:46 <samccann> #chair briantist felixfontein
16:02:46 <zodbot> Current chairs: bcoca briantist felixfontein gundalow samccann
16:03:11 <bcoca> felixfontein: implicit in 'any 2' otherwise it would be same one x2
16:04:29 <acozine> o/
16:04:39 <samccann> #chair acozine
16:04:39 <zodbot> Current chairs: acozine bcoca briantist felixfontein gundalow samccann
16:04:45 <samccann> #topic documentation updates
16:05:06 <samccann> I'll start with the mea culpa - I didn't do any of my action items from last week. I'll get on those after the meeting
16:05:24 <felixfontein> if nobody remembers what the action items are (like me) it's ok ;)
16:05:33 * bcoca googles 'action items'
16:05:57 <acozine> thanks samccann for the comment on my WIP Cheatsheet PR - I think it's a good suggestion (to include the flag in each explanation line), and will incorporate it this week
16:06:16 <acozine> thanks bcoca for the reminder on that same PR that inventory isn't necessarily a file
16:06:25 <samccann> :-)
16:06:48 <acozine> I'll see if I can get the PR ready for prime time by next week
16:06:50 <samccann> I plan on going through the newer issues (docs issues) and start highlighting them here when I can.
16:06:57 <samccann> thanks acozine !!
16:07:23 <samccann> meanwhile I have an interesting PR  that leads to the next topic...
16:07:31 <samccann> #topic Community examples
16:07:48 <samccann> We have the new examples repo that andersson007_ set up.
16:08:02 <samccann> This PR has some interesting detail in the description (not in the PR itself) - https://github.com/ansible/ansible/pull/76702
16:08:35 <samccann> What do folks think, is it something others might find interesting and we ask the PR owner to put them in the examples repo?
16:10:08 * samccann ponders if everyone is busy reading it
16:10:33 <acozine> wow, that's a detailed PR
16:10:44 <acozine> I mean, the description is detailed
16:10:47 <samccann> yes it's a work of art really, isn't it?
16:10:50 <samccann> the description
16:10:50 <acozine> as you say, the changes are very small
16:11:12 <samccann> yeah I'm more asking about all  that description detail. Is it worth putting it someplace so it's not lost?
16:12:00 <acozine> Well, the description is mainly illustrating why setting a user's password to `!` or `*` doesn't really do what the docs suggested it would
16:12:39 <samccann> ah ok. That's why I brought it here :-) I couldn't tell if it was helpful for others or just a very detailed description of the need for the PR change
16:12:49 <felixfontein> if that person has a blog, they should put that in as a blog post
16:13:28 <samccann> #info we're open for community base Ansible examples here - https://github.com/ansible-community/community-examples
16:13:29 <felixfontein> it is a really nice summary, that should be published, but it doesn't really belong in ansible docs IMO.
16:14:54 <acozine> agreed
16:15:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:15:06 <samccann> ok cool, thanks!
16:15:09 <acozine> it's more of a cautionary tale than an example other users would want to follow/adapt
16:15:15 <samccann> lol
16:16:03 <samccann> ok only other documentation item is the docs survey open issues, of which acozine is working on the first one.
16:16:11 <samccann> https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+survey
16:16:33 <samccann> #info a couple more docs survey feedback issues we could use help on - https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+survey
16:16:48 * samccann frequently talks to the meeting minutes ;-)
16:16:54 <acozine> heh
16:17:35 <acozine> I'm thinking for the "cheatsheet" I'll add an entry for `ansible-galaxy` and then just link to the CLI pages
16:18:01 <acozine> then if folks use the page, and want the other commands added. we can revisit
16:18:27 <samccann> is there a simple couple of `ansible-galaxy` commands that people use all the time? like is it worth adding one example to install mynamespace.mycollection ?
16:18:30 <acozine> my guess is that `ansible-playbook` and `ansible-galaxy` are the most frequently used ones
16:18:44 <acozine> yeah, that's what I was thinking
16:19:03 <acozine> list collections, add a collection, publish a collection, probably 3-5 examples for galaxy
16:19:13 <samccann> sounds good, thanks!
16:19:25 <samccann> and as a cheatsheet, I'd limit it to 3 for now
16:20:17 <samccann> one final thing - I started separating the community guide into general, core, and collection-specific - https://github.com/ansible/ansible/pull/76764
16:20:18 <felixfontein> for ansible-galaxy, listing and installing should be the most frequently used ones
16:20:26 <samccann> I'll get that staged later as it will be easier to look at  then.
16:20:54 <samccann> my goal with this PR is to just separate the files out - no real writing /editing happening yet.
16:21:48 <samccann> #info splitting up the community guide into getting started, core, and collection contributor guides - https://github.com/ansible/ansible/pull/76764 (WIP)
16:21:48 <samccann> Thanks felixfontein
16:21:49 <samccann> Anything else in documentation we want to discuss before moving to doctools?
16:22:37 <samccann> #topic generating docs for collections
16:22:49 <samccann> briantist: sounds like you've been busy on that one?
16:23:28 <briantist> on and off yeah, last week was pretty busy so didn't do much during the weekdays
16:23:50 <samccann> #info GitHub actions and reusable workflows you can use to generate documentation in your own collection repository on GitHub -https://github.com/ansible-community/github-docs-build
16:23:51 <briantist> big thanks to felixfontein for some nice contributions, and for reviewing a bunch of PRs I put in over the 3 day weekend
16:24:06 <samccann> woot!
16:24:23 <samccann> so is this actively in use now in a collection or two?
16:24:31 <briantist> so Felix fixed a few bugs, over the weekend I added a job that auto-generates documentation for the actions and workflows to put in the repo's wiki (how meta!)
16:24:37 <felixfontein> most of the work has been done by briantist though :)
16:25:00 <briantist> it is still actively in use the same two collections so far, `community.docker` and `community.hashi_vault`
16:25:22 <briantist> I added automated tests (or the beginnings of them) for two of the actions
16:25:56 <samccann> #info actively in use in `community.docer` and `community.hashi_vault`
16:26:08 <samccann> Did you say you had some docs in a wiki somewhere on how to use all this?
16:26:30 <samccann> cool!
16:26:52 <briantist> there's not much yet, I have more to write, but it's in the repo's wiki: https://github.com/ansible-community/github-docs-build/wiki
16:27:14 <briantist> not much at all on how to actually use it, I expect to do it soon, along with examples, sample workflows, etc.
16:27:33 <gundalow> briantist: Do you think you are ready/happy to announce this in The Bullhorn (or maybe it has already)
16:28:04 <briantist> I'm trying to shore up stuff like testing and docs before adding more features or announcing it more widely, but I am excited about supporting github pages as a publish destination, which I think will end up being the logical choice/easiest path for most maintainers
16:28:11 <acozine> I'd like to see at least one good page on "Why this is such an awesome thing" before we put the project int he Bullhorn
16:28:35 <acozine> the current docs are thorough and useful on the technical side
16:28:47 <briantist> I've brought it up in the Windows Working Group as well, so the Windows collections may be early use cases once the GH pages stuff is tested
16:29:10 <acozine> with a small addition of "here's why you care, here's what the project can do for you and your collection(s)" I think it could be widely adopted
16:29:12 <briantist> (they currently "generate" raw RST docs and commit those in the `docs/` directory of the repos)
16:29:35 <briantist> I agree with acozine , I want more in place before doing a wider announcement
16:29:52 <acozine> in other words, the "how" is there already, we just need to add the "why"
16:29:53 <briantist> but I'd be happy to help anyone who's sufficiently motivated to do something with it earlier
16:30:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:30:04 <briantist> well, we need more "how" as well
16:30:15 <briantist> but yeah "why" too :)
16:30:31 <gundalow> briantist: acozine Cool, all that makes sense
16:30:31 <acozine> I'd be happy to work with you briantist on that content
16:30:42 <samccann> briantist: generating to github pages sounds great. I do worry there will be something between gthub rst and the sphinx rst we support  that might cause people to fix something for github and break it for docs.ansible.com? Not sure really so it's just the paranoid-writer in me saying that
16:31:12 <briantist> github pages would be hosting straight HTML, so just the output of the current generation process
16:32:52 <briantist> does that make sense samccann ?
16:33:19 <samccann> cool
16:33:24 <briantist> acozine: I will reach out regarding new docs, thank you! Also please feel free to review anything already in the wiki
16:33:54 <samccann> gonna shift topics if we are done with this one? Great work briantist !
16:34:19 <samccann> briantist: yeah it does.
16:34:23 <briantist> yup sounds good to me, anything felixfontein had anything to add on this topic
16:34:28 <briantist> unless*
16:34:31 <samccann> where is the wiki?
16:34:49 <acozine> https://github.com/ansible-community/github-docs-build/wiki
16:34:50 <briantist> whoops though I copied the link and forgot to paste: https://github.com/ansible-community/github-docs-build/wiki
16:34:55 <samccann> thanks!
16:35:13 <samccann> #info some early docs available at https://github.com/ansible-community/github-docs-build/wiki
16:35:44 <samccann> ok I have the smallest of small updates on ...
16:35:53 <samccann> #topic semantic markup
16:36:16 <felixfontein> yay, updates ;)
16:36:21 <samccann> So I have an internal product manager helping me out now to navigate the ins and outs of getting this reviewed and hopefully on a roadmap somewhere
16:36:34 <briantist> nice!
16:36:40 <felixfontein> good news :)
16:37:01 <samccann> #info we found out definitively that this will impact Automation Hub/ GalaxyNG so need to coordinate with that team
16:37:01 <acozine> ooh, that's excellent
16:37:33 <samccann> aka they use `ansible-doc --json` and thus need to determine the impact and when they can support it etc.  Slow process but making baby steps!
16:37:57 <bcoca> also devtools team, ansible-navigator does it's own doc display
16:38:23 <samccann> so as a reminder, not going to make core 2.13 for sure. I'm crossing fingers for 2.14, but at least I feel I'm using the correct internal process now.
16:38:51 <samccann> yeah Brad on ansible-navigator said no significant impact, but it's still on the list to make sure during the official internal review etc
16:38:57 <briantist> ah, that's unfortunate, but glad to hear it's on a good track now
16:39:05 <felixfontein> yep
16:39:47 <samccann> on the plus side, felixfontein has been putting a lot of features into this during this.. ahem.. delay.  So we have a solid proposal.
16:40:07 <briantist> woooo!
16:40:21 <felixfontein> the thing is, everything that's not in by now (or soon) will take another similar long round to get included, so if you have something else... :)
16:40:25 <samccann> Which is good because - this is kinda painful to coordinate, so better to have one big idea than what I'm used to really - a small idea, release it, add to it, again and again til it's fantastic ;-)
16:40:38 <samccann> exactly felixfontein
16:41:10 <samccann> #info if anyone has additional ideas for semantic markup improvements, now's the time to get them in before the design goes for internal review with the GalaxyNG teeam!
16:41:28 * briantist gets pulled away by a burrito 🌯delivered earlier than expected 😋
16:42:04 <samccann> #info proposal - https://hackmd.io/VjN60QSoRSSeRfvGmOH1lQ
16:42:14 <samccann> omgosh i'm craving burritos now!
16:42:15 <felixfontein> briantist: enjoy!
16:42:33 <acozine> mmmm, burrito
16:42:39 <samccann> felixfontein: anything we should specifically do this week to ensure we have the best design for this now?
16:43:41 <felixfontein> samccann: I don't think there is
16:44:11 <felixfontein> though the 'one big thing' makes me think whether we should add support for `seealso:` for plugins
16:44:14 <samccann> ok cool
16:44:26 <felixfontein> right now you have to use a RST reference to reference to plugins, as opposed to modules
16:45:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:45:01 <samccann> ah so `seealso:` works if i reference a module, but not for a plugin
16:45:10 <acozine> could we expand the existing `seealso` to use FQCN?
16:45:52 <acozine> or are you thinking that we create a separate approach for non-module plugins?
16:46:04 <bcoca> i would create generic that applies to all
16:46:17 <samccann> we could think about this as 'the last chance we have to do fancy stuff to module/plugin docs for the next 2 years'
16:46:27 <bcoca> fqcn lacks the 'plugin type' , so you need extra data to diffrenciate
16:46:39 <acozine> samccann: jeez, no pressure, eh?
16:46:39 <bcoca> p(fqcn, type)
16:47:01 <samccann> heh well bcoca - the `ansible-doc --json` stuff is what I'm specifically thinking about
16:47:17 <felixfontein> right now there's `module:`, we could have `plugin:` combined with `plugin_type:`
16:47:21 <bcoca> that passes 'transparently' so the consumer needs to deal with it
16:47:47 <felixfontein> which is why it has to go into this round, if we want to have it soon :)
16:47:48 <bcoca> felixfontein: easier to have just one method in the end, i woudl deprecate module:
16:48:24 <felixfontein> bcoca: it would still have to stay there for a looong time, and modules are the most frequently used so having a special case for them can be justified IMO
16:48:48 <samccann> bcoca - what's the impact on say 3K modules that may or may not already use module: ?
16:49:16 <samccann> the current semantic markup doesn't force anyone to change existing module docs unless they want to, is my point I guess
16:49:48 <bcoca> phase out over time, i said deprecate, not remove
16:50:18 <felixfontein> deprecation is something that can be done later on, it doesn't require interaction by any of the consumers
16:50:32 <bcoca> samccann: it does not 'force' but can make things look wierd when user has no idea what C(stuff) means
16:50:34 <felixfontein> that's why I would keep it out of the current proposal, since it's easy to add later on
16:50:59 <bcoca> felixfontein: yes, deprecation is for authors, not consumers
16:51:14 <samccann> ok so the benefit of phasing out (over years really) is that the code would be.. concise? one feature that covers modules and plugins.
16:51:33 <bcoca> also makes it easier to modify and adjust in one function vs one per
16:51:44 <samccann> the drawback would be...at some point, collection owners would have to change their stuff or we could never actually remove it?
16:52:16 <bcoca> add it to the validation rules as warning, it will happen organically
16:52:33 <acozine> I guess at some point we could tell folks "update your collection or we boot it out of the Ansible package"
16:52:35 <felixfontein> samccann: yes, it will need to stay possible to use for years. and there needs to be a way to emit these deprecation warnings so they don't annoy end-users
16:53:01 <acozine> put the deprecation into the docs build, maybe?
16:53:18 <felixfontein> acozine: then samccann will see them, but not the docs authors :)
16:53:23 <acozine> though maybe collection maintainers woudln't seee it there
16:53:31 <acozine> heh, yep
16:53:44 <felixfontein> `ansible-test sanity` would be a good place, but that doesn't really have an infrasturcture for non-error warnings yet I think
16:53:51 <felixfontein> (at least nothing users would notice)
16:54:12 <samccann> we have 5 min left
16:54:50 <samccann> so next steps would be to write up this addition to the proposal (and decide to deprecate vs not deprecate?)  So the code iself would work for both modules and plugins either way, right?
16:54:50 <felixfontein> samccann: thanks for posting the a18y issue in the antsibull repo btw!
16:55:09 <felixfontein> s/a18y/a11y/
16:55:13 <felixfontein> (counting is hard)
16:55:17 <acozine> heh, I wondered
16:55:42 <felixfontein> accessassabililility
16:56:14 <samccann> haha yep
16:56:20 <felixfontein> I would not deprecate in this proposal, just add a new way
16:56:23 <samccann> Ok we have 3 minutes for a quick openfloor
16:56:26 <felixfontein> (as deprecations can be done later on)
16:56:31 <felixfontein> I can write something up
16:56:32 <samccann> #topic Open Floor
16:56:47 <felixfontein> (and implement it in the PRs)
16:57:09 <samccann> #action felixfontein to write up an addition to the semantic markup to support seealso: for plugins as well as modules
16:57:35 <samccann> Okay this is the time to bring up anything docs related. Have a fav PR or issue you want to discuss? now's the time!
16:58:01 <briantist> seealso: support for plugins would be great; trying to get the RST refs right for that is a big part of what inspired me to work on the docs build process 😅
16:59:27 <briantist> (so I could see quickly whether I got it right or not. Hint: I got it wrong many many times!)
16:59:42 <samccann> i have one quick issue - https://github.com/ansible/ansible/issues/76609
17:00:03 <samccann> it's more cli help than docs. I'm not sure what the 'waiting on contributor' label means?
17:00:22 <briantist> ah I remember that, I helped him a bit on IRC and encouraged him to submit an issue
17:01:06 <briantist> for those of us who have used `ansible-test` since before split-controller, it's easier in that we can mostly ignore the new options and use what we used before, but that is less clear to a new user
17:01:30 <acozine> `waiting_on_contributor` means "we think this is worth doing but we don't have anyone lined up to do it, so we're waiting for someone to step forward and do this work", more or less
17:01:59 <felixfontein> I would still argue that `--help` output should document everything, but not be a complete man page with howtos etc.
17:02:05 <acozine> so, should the cheatsheet include `ansible-test`?
17:02:12 <briantist> I did look at the help, and it is accurate, but it took me a little while too to parse out how to find the original/simple invocation from everything it shows
17:02:26 <acozine> maybe one or two examples of simple use cases?
17:02:26 <briantist> I don't have any recommendation on how to improve the help output though..
17:02:27 <bcoca> --help = all options, short desc
17:02:30 <samccann> acozine: thanks for the explanation!!
17:02:36 <bcoca> man <> == fulldocs
17:02:51 <briantist> as felixfontein and bcoca said, what it shows is probably the right amount/level of information
17:03:11 <felixfontein> if we have a page somewhere (cheatsheet for ansible-test), we could insert a link to that though, but I wouldn't add even more output to --help (except possibly a reference to an URL)
17:03:13 <samccann> briantist: ah this is a split controller confusion? Yeah we lack docs on that for sure (docs.ansible.com)
17:03:16 <briantist> maybe a cheatsheet or other page with examples and deeper explanation is best
17:03:23 <acozine> briantist: would you be willing to add your "usual command" for ansible-test to the cheatsheet PR?
17:03:40 <felixfontein> samccann: the confusion comes from split-controller adding a LOT of new options to ansible-test
17:04:10 <samccann> ok thanks felixfontein
17:04:16 <felixfontein> the cheatsheet should also mention the correct directory structure if it mentions ansible-test :)
17:04:33 <briantist> I guess there's no single "usual command" but there is a simpler syntax where you don't actually specify separate controller and target options
17:04:55 <acozine> yeah, just an example or two of the simpler syntax
17:04:59 <samccann> #action samcann acozine - to review https://github.com/ansible/ansible/issues/76609 in terms of how we can add to the cheatsheet and/or create split controller docs to help out here  (and eventual URL added to `ansible-test --help1` output
17:05:01 <felixfontein> the 'usual command' depends on what kind of test should run :)
17:07:14 <samccann> ok looks like it's about time to wrap up for today
17:07:15 <acozine> woopsie, i need to run
17:07:23 <acozine> thanks, everybody!
17:08:00 * acozine will be back on IRC/Matrix this afternoon
17:08:05 <samccann> #endmeeting