15:59:25 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:59:25 <zodbot> Meeting started Tue Jan  4 15:59:25 2022 UTC.
15:59:25 <zodbot> This meeting is logged and archived in a public location.
15:59:25 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:59:25 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:59:25 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:59:31 <briantist> o/
15:59:31 <samccann> #topic opening chatter
15:59:38 <remindbot[m]> @smccann:matrix.org Hi Everyone! We could use some help with these easyfix docs issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs+label%3Aeasyfix
15:59:38 <acozine> o/
15:59:48 <acozine> heh, the remindbot is joining in!
15:59:51 <felixfontein> o/
15:59:58 <samccann> #chair briantist acozine felixfontein
15:59:58 <zodbot> Current chairs: acozine briantist felixfontein samccann
16:00:22 <samccann> @room Meeting time! Who is here to talk the docs?
16:01:27 <samccann> andersson007_: tadeboro cyberpear around to talk docs?
16:01:55 <samccann> btw there was a LOT of chatter here this past week so if I missed anything important, please let me know
16:02:10 <samccann> not sure I can do the full on weeks worth of scrollback and make sense of it all
16:02:51 <briantist> most of that chatter was from me, re: the docs build process 😁 which I can talk about whenever it's the right time in the meeting for the topic
16:02:58 <samccann> and another btw - I have to scoot early for a doc apt (like 45 min into the meeting probly) but y'all can keep going so long is someone's up for  the endmeeting at the... end
16:03:12 <felixfontein> I did some more work on semantic markup and some other docs related PRs
16:03:12 <samccann> cool thanks briantist
16:03:45 <samccann> neat. I need to start cracking the whip internally on that one to get feedback on the proposal. it's gotten..erm... silence so far
16:04:06 <felixfontein> the current WIP implementation now has links
16:04:12 <acozine> felixfontein: any of those PRs ready for review?
16:04:15 <acozine> oooh, nice
16:04:25 <samccann> #info new agenda issue for the new year! https://github.com/ansible/community/issues/643
16:04:36 <samccann> #topic semantic markup
16:04:38 <felixfontein> example: https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_set_module.html#parameters
16:04:44 <samccann> since we're talking about it ;-)
16:05:14 <samccann> #info example - https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_set_module.html#parameters
16:06:08 <samccann> hmm... shouldn't hotlinks be in blue? I didn't really notice them until my mouse scrolled by on the bold red
16:06:20 <felixfontein> it's not really defined :)
16:06:38 <acozine> but with semantic markup we can change the look any time we want!!!!
16:06:39 <felixfontein> right now I colored them the same as other teletype text
16:06:46 <felixfontein> indeed :)
16:07:06 <felixfontein> here's another example with lists and suboptions: https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_sets_module.html#parameters
16:07:13 <acozine> I agree that they don't current "read" as links, though they do look sharp.
16:07:13 <samccann> actually we should evaluate what links should look like for accessibility.  Just thinking blue wouldn't work for the color-blind, but anyway, WOOT for links!!
16:07:26 <samccann> #info here's another example with lists and suboptions: https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_sets_module.html#parameters
16:07:29 <acozine> underlining, maybe?
16:08:03 <samccann> #action @samccann to push more on the semantic markup review internally and include the example links
16:08:10 <samccann> yeah underlining might help.
16:08:44 <felixfontein> underlining and/or color. I'm not sure which would be best, I guess there will also be different opinions on this :)
16:08:54 <samccann> I was looking at the core roadmap and I think 2.13 branch is pulled end of March so that's my target - to get internal agreement by then so we can start merging PRs for devel or something.
16:09:04 * samccann thinks there's more to that, but brain is still on holiday
16:09:32 <samccann> Anything else on semantic markup before we tiptoe to another topic?
16:10:10 <felixfontein> I updated the specs, also with that [] notation (which I introduced while working on that PR) - if you have comments on that, please tell me (or put them in the issues/PRs/...)
16:10:24 <felixfontein> (and no need to come up with comments right now :) )
16:10:51 <briantist> no real comments on this stuff from me, other than I'm really looking forward to semantic markup!
16:12:11 <samccann> [] notation makes sense to me
16:12:38 <samccann> ok new topic
16:12:46 <samccann> #topic documentation work
16:13:25 <samccann> #info please help with the docs issue backlog - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs including some easyfix items https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs+label%3Aeasyfix
16:13:34 <samccann> ^^ for those reading the minutes :-)
16:13:57 <samccann> This section of the agenda focuses on the words (aka docs themselves) vs the docs tooling like semantic markup
16:14:31 <samccann> #info comments/approvals of docs PRs from the technical perspective always helps to move them to final merging! - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs_only
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:08 <samccann> heh
16:15:10 <acozine> I was thinking about one of those issues
16:15:17 <felixfontein> samccann: can you re-trigger CI for https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+author%3Afelixfontein+label%3Abackport ?
16:15:20 <samccann> cool cool!
16:15:32 <acozine> the "cheatsheet" idea for the CLI commands
16:15:46 <acozine> https://github.com/ansible/ansible/issues/75509
16:16:28 <samccann> yeah that one sounds like a great idea acozine .
16:16:32 <acozine> I put a comment on it that links to the main page for CLI docs
16:16:40 <felixfontein> indeed!
16:16:44 <samccann> felixfontein: gave CI a boot in the backside. 🤞it works now
16:17:08 <felixfontein> samccann: thanks :)
16:17:15 <acozine> and it would be easy enough to add a page, but where should it go?
16:17:19 <felixfontein> samccann: btw, https://github.com/ansible/ansible/issues/76495 - it is EOL by now
16:17:48 <felixfontein> (I would mention it in the issue but I'm not anywhere near my GH account righ tnow...)
16:18:02 <samccann> acozine: What we really need is a getting started. I bet new folks just can't find that page
16:18:14 <acozine> hm, yeah
16:18:16 <samccann> felixfontein: yep on my todo list for this week, thanks for the reminder!
16:20:12 <samccann> acozine: I would think we just add a new doc under the using ansible. Could even call it 'getting started' and just put the cookbook examples there for now.
16:20:14 <acozine> yerg, that quickly gets into the thorny issue of the main TOC
16:20:23 <acozine> we've got a page called intro_getting_started
16:20:29 <acozine> https://docs.ansible.com/ansible/latest/user_guide/intro_getting_started.html
16:20:41 <acozine> it's a guided walkthrough
16:20:43 <acozine> but kinda buried
16:21:02 <samccann> yeah, to me, that's not a getting started
16:21:17 <samccann> the network getting started is far better imo and should have a generalized version
16:25:42 <acozine> I'm not sure a "cheatsheet" is going to be much help for complete newcomers. i was thinking of it more as a reminder for more experienced users - a place where you could quickly see the command-line flags for things like connection user, etc.
16:26:00 <acozine> But better content for newcomers is definitely needed!
16:26:12 <samccann> ah gotcha.
16:26:36 <samccann> i'll have to think about where to put it but if you are up for creating one, then go for it!
16:26:53 <acozine> I'll work on a draft
16:27:04 <samccann> we can decide where to put it when you have a PR ready to look at.
16:27:09 <samccann> cool thanks!
16:27:30 <samccann> #action acozine to work on creating command cheat-sheet for that issue
16:27:44 <samccann> #topic Docs tooling
16:27:58 <samccann> briantist: go for it on the docs build process!
16:28:04 <briantist> cool ok!
16:28:37 <briantist> so I spent a good part of my holiday break re-implementing the docs build process into self-contained github actions and reusable workflows
16:29:17 <briantist> they are parameterized and I think I've struck a good balance to where we can quickly and minimally build docs for collections, but also customize the process for most use cases
16:29:22 <samccann> is this the build collection docs with a PR stuff?
16:29:29 <briantist> yes!
16:29:42 <samccann> woot!!!
16:29:57 <samccann> can you sprinkle some info links here so others can take a look?
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:03 <briantist> I put up a PR in `community.docker` that felixfontein was nice enough to merge and troubleshoot with me, so as an example, this is all that was added: https://github.com/ansible-collections/community.docker/blob/main/.github/workflows/docs-pr.yml
16:30:24 <felixfontein> you can look at the edit history of this comment: https://github.com/ansible-collections/community.docker/pull/264#issuecomment-1003616626
16:31:05 <briantist> for my collection, which includes a publish step, and some customization (I commit the output of `antsibull sphinx-init`), it's not much more complicated: https://github.com/ansible-collections/community.hashi_vault/blob/main/.github/workflows/docs.yml
16:31:07 <samccann> #info example of the docs workflow in action for a collection-level PR - https://github.com/ansible-collections/community.docker/blob/main/.github/workflows/docs-pr.yml
16:31:52 <briantist> for now, the shared actions and workflows live in the `community.hashi_vault` repo, but they should be moved to their own project(s) so that they can be treated as the separate projects they are
16:32:25 <briantist> there is some question as to whether they should all be in one repo, or be in separate repos.. not sure if we want to have that discussion just yet (probably better to have async in an issue)
16:32:32 <samccann> #info another example which includes a publish step, and some customization (I commit the output of `antsibull sphinx-init`), it's not much more complicated: https://github.com/ansible-collections/community.hashi_vault/blob/main/.github/workflows/docs.yml
16:32:59 <samccann> #info the shared actions and workflows live in the `community.hashi_vault` repo, but they should be moved to their own project(s) so that they can be treated as the separate projects they are
16:33:03 <briantist> but, it is in a good state where I can work with any other collection maintainers who are interested to get it going
16:33:44 <briantist> The actions are here: https://github.com/ansible-collections/community.hashi_vault/tree/main/.github/actions/docs
16:33:46 <samccann> yeah maybe an async in community-topics? The target audience is collection developers to the details just WHOOOSH right over my head right now
16:33:53 <samccann> but looks like great progress!
16:34:05 <samccann> #info The actions are here: https://github.com/ansible-collections/community.hashi_vault/tree/main/.github/actions/docs
16:34:16 <briantist> shared workflows are here (they must be mixed with non-shared workflows, so I pre-pended all with `_shared`): https://github.com/ansible-collections/community.hashi_vault/tree/main/.github/workflows
16:34:22 <felixfontein> I'm +1 for a repo for these actions and workflows (but not multiple ones)
16:34:33 <samccann> #info hared workflows are here (they must be mixed with non-shared workflows, so I pre-pended all with `_shared`): https://github.com/ansible-collections/community.hashi_vault/tree/main/.github/workflows
16:35:08 <felixfontein> I think we can continue that discussion in https://github.com/ansible-community/community-topics/issues/40
16:35:30 <briantist> I'm not opposed to a single repo, I only want to first ensure that we understand the consequences of that as far as releases, breaking changes, etc.
16:35:52 <briantist> felixfontein: that issue overlaps some, but perhaps it's best to have a separate one for the docs stuff specifically?
16:36:04 <felixfontein> since the docs actions and workflows are somewhat coupled, I would have them all in one repo
16:36:19 <felixfontein> briantist: good question. both is fine for me. whatever you prefer :)
16:37:04 <samccann> #info continue the discussion at https://github.com/ansible-community/community-topics/issues/40
16:37:11 <briantist> I'd say separate issue then, and honestly, I am leaning single repo too, but I will open the issue generally
16:37:14 <samccann> #undo
16:37:14 <zodbot> Removing item from minutes: INFO by samccann at 16:37:04 : continue the discussion at https://github.com/ansible-community/community-topics/issues/40
16:37:37 <samccann> heh okay I need to skeedaddle for the doc apt. Please continue and can someone endmeeting when all is done?
16:37:42 <acozine> I'd say the more we can consolidate, the better
16:37:54 <felixfontein> brb, changing computer
16:38:03 <acozine> so i'd vote single repo unless I hear compelling arguments for splitting things up
16:38:11 <acozine> samccann: hope hte doc appt goes well
16:38:14 <acozine> I can close hte meeting out
16:38:23 <samccann> cool thanks!
16:38:49 * acozine hopes she really does have that power
16:39:23 <acozine> briantist: thanks for generalizing your work so it can be shared
16:39:35 <briantist> 👍
16:39:36 <felixfontein> re
16:39:56 <briantist> any additional questions about that work?
16:40:15 <acozine> er, not yet, but I haven't read the PRs yet really
16:40:35 <acozine> I'd like to understand it better
16:41:41 <acozine> did you create a docs-specific issue for ongoing conversation?
16:41:56 <briantist> in the process of creating it now
16:42:06 <acozine> awesome, thanks
16:42:13 <briantist> but also being pulled in several directions, so might not be until a little later
16:42:25 <acozine> I hear you
16:42:39 * acozine hears slacking pinging again
16:43:04 <acozine> no hurry, there's plenty there to read
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:03 <acozine> anything else on the tooling side we should discuss?
16:45:38 * acozine checks the agenda
16:46:21 <felixfontein> I did update the links PR: https://github.com/ansible-community/antsibull/pull/355
16:47:13 <felixfontein> the buttons now have another color, and I reduced the number of 'standard' buttons: https://ansible.fontein.de/collections/community/dns/index.html#plugins-in-community-dns https://ansible.fontein.de/collections/community/hashi_vault/index.html#community-hashi-vault
16:47:24 <felixfontein> (the first one has some extra links, the second does not)
16:47:43 <acozine> nice!
16:48:22 <acozine> what did we decide about email addresses?
16:48:40 <acozine> ah, nvmnd
16:48:44 <felixfontein> I don't think there was any decision
16:48:44 <acozine> I see the comment
16:49:44 <felixfontein> then there's also still the plugin type discussion outstanding (discussion: https://github.com/ansible-community/community-topics/issues/57, PR: https://github.com/ansible-community/antsibull/pull/364)
16:50:37 <acozine> I'm +1 on both of those
16:51:21 <felixfontein> acozine: please put your opinion in the discussion issue as well :)
16:51:36 <acozine> will do
16:51:41 <felixfontein> thanks!
16:52:11 <felixfontein> right now the issue is pretty short on opinions, which doesn't help creating a more community wishes taylored proposal
16:52:35 <felixfontein> bcoca: feel free to also put your opinion in https://github.com/ansible-community/community-topics/issues/57
16:52:42 <acozine> heh, yeah, I just saw the triple-choice part
16:52:48 <acozine> that will take slightly more thought
16:52:58 <felixfontein> no need to hurry :)
16:53:05 * acozine opens another tab in her "action required" section
16:53:15 <felixfontein> (everyone else is of course also invited!)
16:53:28 <acozine> well, not hurry, no, but it would be good to take steps forward on all of this
16:54:14 <acozine> I find the voting options a bit confusing
16:54:43 <acozine> in a good way, it's nice to have granular options, but it's not a simple/quick +/-
16:54:53 <acozine> yikes, five minutes left
16:54:58 <acozine> okay, quick open floor
16:55:05 <acozine> #topic open floor
16:55:11 <felixfontein> yeah, the idea is to get some voices so it's possible to create a simpler proposal that just requires + and - :)
16:55:13 <acozine> oh, good, that worked
16:55:22 <acozine> heh, yep
16:55:25 <acozine> it's a process
16:56:24 <acozine> now is the moment, folks - if you have been watching the chat go by and thinking "nobody's talking about this other important issue" . . . please join the conversation!
16:56:52 <acozine> issues, PRs, questions all welcomc
16:56:55 <acozine> er, welcome
16:57:43 <felixfontein> samccann: can you trigger just the failed runs in https://github.com/ansible/ansible/pull/76574 and https://github.com/ansible/ansible/pull/76575 ?
16:58:43 <acozine> the Docs Working Group meets every week here in the IRC/Matrix chat, and all are welcome to join!
16:58:57 <samccann> felixfontein: not sure how?
16:59:09 <samccann> (In car but not driving)
16:59:38 <acozine> I've got another meeting at the top of the hour today
16:59:42 <felixfontein> samccann: you might be able to click on 'Details' next to the 'CI' job, and then click 'Retry' next to one of the jobs in the list on the left side
16:59:45 <acozine> so I'm going to close out the DaWGs meeting
17:00:04 <felixfontein> at least that works with AZP in collections, I'm assuming it will also work with AZP in ansible/ansible then
17:00:18 <acozine> thanks briantist and felixfontein for the fantastic ideas and PRs
17:00:32 <acozine> see you next week
17:00:47 <acozine> #endmeeting