15:01:46 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:46 <zodbot> Meeting started Tue May 10 15:01:46 2022 UTC.
15:01:46 <zodbot> This meeting is logged and archived in a public location.
15:01:46 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:46 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:46 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:56 <samccann> #topic opening chatter
15:02:03 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:11 <briantist> o/
15:02:13 <briantist> sorta here
15:02:14 <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:21 <samccann> #chair briantist
15:02:21 <zodbot> Current chairs: briantist samccann
15:02:32 <samccann> too late, you're furniture now!
15:02:42 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1116267402
15:02:52 <briantist> there are worse things to be
15:03:45 <samccann> heh
15:03:50 <samccann> could be a quiet day
15:05:20 <samccann> #topic Documentation updates
15:05:34 <samccann> #info moving collection-level dev guides out to their collection repos - https://github.com/ansible-community/community-topics/issues/91
15:06:29 <samccann> Shout out to mariolenz for the work and suggestions.
15:06:44 <samccann> About 1/2 are moving, the others I opened issues in their repos to request the move
15:07:07 <samccann> Need to create a similar topic to track all the scenario guides (loads of them) that really need to move as well.
15:07:28 <acozine> o/
15:07:40 <acozine> I've got one thing to clear up
15:07:41 <samccann> #chair acozine
15:07:41 <zodbot> Current chairs: acozine briantist samccann
15:07:45 <acozine> but make me furniture now
15:07:48 <acozine> and I'll be right back
15:07:59 <samccann> yep.. furniture flies fast and furious here in DaWGs land!
15:08:27 <samccann> #info starting the new getting started guide. Add comments to the issue if you have ideas/suggestions - https://github.com/ansible/ansible/issues/77681
15:08:48 <samccann> We got a lot of feedback in reddit on this one as well so some great ideas
15:10:46 <samccann> and my starting point will be generalizing the network getting started that acozine created... cuz it's good ;-)
15:10:56 <acozine> okay, I'm back
15:11:01 <acozine> heh, just in time to hear my name
15:11:05 <samccann> just in time for some praise!
15:11:38 * acozine blushes
15:11:48 <samccann> #info down to 100 open docs issues! (from 133).
15:12:17 <acozine> wow, very impressive!
15:12:20 <samccann> ^^ has more to do with what I'm guessing is an overall effort by the core team to work on issue backlog. But also getting some community help with easyfix items so it's all good!
15:13:34 <acozine> do we have a way to add the Reddit feedback to the issue (for Getting Started)?
15:13:50 <samccann> oh good idea, I can add a link to it in the issue for tracking
15:13:55 <acozine> does Reddit have permalinks?
15:14:06 <acozine> I don't know much about Reddit
15:14:26 <samccann> #info reddit feedback on getting started - https://www.reddit.com/r/ansible/comments/udy8ke/feedback_wanted_updating_the_ansible_getting/
15:14:29 * samccann loves reddit
15:14:45 <samccann> well for this anyway. Gotten some great tidbits when I ask for help
15:15:15 <acozine> I posted that link into the issue
15:15:19 <samccann> oh you just beat me to it lol!
15:15:25 <samccann> cool, thanks!
15:15:25 <acozine> heh
15:15:32 <acozine> I had them both open and had that thought top of mind
15:15:42 <samccann> #info always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
15:15:53 <samccann> ok that's about that on words on paper updates
15:16:02 <samccann> #topic Doctools
15:16:53 <samccann> shout out to felixfontein for getting support in `antsibull-docs` for sidecar docs
15:16:56 <samccann> #link https://github.com/ansible-community/antsibull-docs/pull/6
15:17:10 <acozine> W00t!
15:17:16 <samccann> I think there may be more going on there, but it's a start for sure.
15:17:20 <briantist> yay!
15:17:42 <samccann> #info sidecar docs are a 2.14 feature so docsite support will not show up until 2.14 releases, except on devel at some point
15:18:01 <briantist> I've put my own PR on hold for filter docs for that reason
15:18:04 <samccann> ^^ depends on pushing an update to the test container images so we aren't rushing it.
15:18:40 <briantist> uncertainty about where they will show up, and when, and incongruity between my collection's docs build/verification
15:18:45 <samccann> Any updates on collection docs stuff briantist ?
15:18:57 <briantist> in case anyone wants to comment on my thinking around it: https://github.com/ansible-collections/community.hashi_vault/pull/263
15:19:07 <briantist> other updates on docs build stuff:
15:19:35 <briantist> `community.aws` is using it, partially. I did leave them a note in IRC that the publish ability is ready now so they can use that too, but no response...
15:19:59 <briantist> I have a PR open in `community.windows` to get that collection using it (with `ansible.windows` to follow if all goes well)
15:20:11 <acozine> that's awesome!
15:20:13 <samccann> cool that's great progress!
15:20:17 <briantist> that'll be nice for that collection because it can replace the mnaully generated RST docs sitting in their `docs/` folder
15:20:23 <felixfontein> o/
15:20:26 <briantist> will  bring it up again in today's Windows Working Group
15:20:34 <felixfontein> was too fast on the bike, so I got on a train earlier :)
15:20:35 <samccann> #chair felixfontein
15:20:35 <zodbot> Current chairs: acozine briantist felixfontein samccann
15:20:44 <samccann> haha cool!
15:20:50 <samccann> peddle power FTW
15:20:55 <acozine> speed demon Felix!
15:22:03 <samccann> Any antsibull-docs updates to chat about felixfontein ?
15:22:28 <felixfontein> ah, yes, actually there's one thing :)
15:22:37 <felixfontein> #link https://github.com/ansible-community/antsibull-docs/pull/8
15:22:39 <samccann> #info `community.aws` is partially using the docs build work by briantist
15:23:04 <felixfontein> I've started a PR for supporting `plugin:` seealsos. that's from the semantic markup spec, and bcoca wants to use it in test/filter docs.
15:23:14 <briantist> yesssssss
15:23:26 <samccann> #info support coming for seealso in plugin docs
15:23:37 <felixfontein> I think it's safe to merge this since for modules and other plugin kinds, you cannot pass ansible-test validation when using this
15:23:38 <samccann> coolness!
15:24:01 <samccann> so because it has the word semantic markup - I assume this has no impact on existing stuffs... only new stuff in the test/filter sidecar docs work, yes?
15:24:18 <felixfontein> so this shouldn't be a problem for AH & friends that also render docs. and if they support test/filter plugins they have to handle it anyway when it is used in ansible-core itself
15:24:59 <felixfontein> you *can* also use it in existing plugins and modules, but you can put all kind of "invalid" syntax in there. if someone uses that, there's no guarantee that any docs renderer will handle it correctly, so it shouldn't be a problem for AH and riends
15:25:03 <felixfontein> +f
15:25:05 <felixfontein> IMO :)
15:25:08 <samccann> #info this addition has no impact on AH etc as they will need to support their own version of seealso when they support sidecar docs
15:25:21 <felixfontein> as opposed to other semantic markup things; these appear in already supported documentation parts
15:25:49 <samccann> coolness. thanks for this!
15:26:08 <bcoca> s/want/was asked to, then corrected/
15:26:59 <felixfontein> bcoca: btw, could you please add my suggestions (https://github.com/ansible/ansible/pull/77687#discussion_r866319112 and the one below)? plugins seealso requires FQCNs same as regular seealso
15:27:20 <briantist> I still can't parse what was said about when/whether/how it's safe to use the new thing... will have to figure that out, but I very much want it, since I make heavy use of `seealso:` links to other plugins, and the `ref:` form I use now is cumbersome (but works).
15:28:02 <felixfontein> briantist: since you have a community collection, that's not RH certified, I guess you can ignore AH and just use it. you just have to ignore the validate-modules syntax errors you'll get
15:29:08 <briantist> also felixfontein if you could take a look at the PR I linked about re: filter docs (no rush) I would appreciate it. It's a somewhat similar situation, I'm holding off around uncertainty of supportability and validation
15:30:08 <felixfontein> briantist: note that cetain Supported collections already have documentation for filters and tests (inside the .py file)
15:30:37 <briantist> right...
15:32:10 <felixfontein> I'm not sure about the .yml sidecar files, but I would be really surprised if they break anything. if they break ansible-doc from devel (in the sense that it crashes), it's likely a bug in ansible-doc that should be fixed anyway before devel becomes stable-2.14
15:33:19 <felixfontein> anyway, does anyone mind if I merge https://github.com/ansible-community/antsibull-docs/pull/8 ? or does someone wants to review it first?
15:33:50 <briantist> well, we don't have to spend meeting time on it, some of it is just conflict over whether I can use docs build to validate, and conflict over the pros and cons of running docs build on devel, etc. Probably just the perfectionist in me agonizing over not having a perfect solution ;)
15:34:19 <acozine> felixfontein: I don't have the coding skills to review that PR fully, but at a high level it looks good to me
15:34:37 <briantist> lgtm, I thought I approved it already but I guess I just emoji reacted haha
15:34:59 <samccann> felixfontein: I can't really comment on the code, but I can +1 the feature ;-)
15:35:07 <felixfontein> ok cool :) thanks everyone!
15:35:52 <acozine> one question
15:36:16 <acozine> is there a reason behind the order of the list in lines 514-517?
15:36:49 <acozine> `mod` then `plugin` then `ref` then `link`?
15:36:59 <felixfontein> I was about to say 'alphabetical ordering', and then I noticed the last element
15:37:00 <acozine> my brain automatically wants to alphabetize it, but the order looks deliberate
15:37:06 <acozine> heh
15:37:25 <felixfontein> might be a random artefact... I'll try to change it and see what happens :)
15:37:40 <acozine> heh, okay
15:38:25 <acozine> if the tests fail on that change, I'll be in awe of the randomness of the universe
15:38:46 <acozine> or maybe I should say, if the tests do not fail on that change
15:42:02 <felixfontein> seems to make no differene ace at all
15:42:03 <samccann> #topic Open Floor
15:42:12 <samccann> Do we have other lingering topics to chat bout today?
15:42:42 <acozine> every time I see "open floor" I think about doing a flash-mob dance of some kind
15:43:04 <samccann> -\o/-
15:43:13 <samccann> my idea of a flashmob lol
15:43:16 <felixfontein> :)
15:43:29 <acozine> if we ever have a community/contributor summit in person, I think we need to have an "Open Floor Night" or something
15:43:50 <samccann> haha
15:44:25 <samccann> So one thing I can mention - we have some community docs writers helping out in PRs and some easyfix issues
15:44:35 <acozine> --\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/
15:44:54 <samccann> WOOT! DaWGs first FLASH MOB ascii style!
15:45:01 <acozine> * --\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--\o/--
15:45:23 <acozine> hooray for community docs writers
15:45:23 <briantist> I would like to go an in person summit at some point
15:45:28 <acozine> any PRs you want to highlight?
15:45:32 <acozine> briantist: oh, me too!
15:45:58 <acozine> samccann: the PRs-to-highlight was at you
15:46:25 <samccann> yes - https://github.com/ansible/ansible/pull/77728
15:46:29 <samccann> it needds a developer to approve
15:46:36 <felixfontein> ok, my train arrives very soon, so I'll be off until later this night :)
15:46:41 <felixfontein> see you around!
15:46:45 <samccann> thanks felixfontein !!
15:46:47 <acozine> happy commuting felixfontein !
15:47:35 <samccann> this one could do with another opinion as well - https://github.com/ansible/ansible/pull/77725
15:47:52 <samccann> maybe a tiebreaker between felixfontein and bcoca :-)
15:49:06 <acozine> erm, that one's a bit over my technical head
15:49:34 <samccann> yeah me too
15:50:00 <samccann> oh one thing came out of the reddit thread that was interesting - the idea of a 'getting started' for jinja2
15:50:17 <samccann> I know that's been a problem area for us. Maybe we don't write one but can find one online we can point to?
15:50:35 <acozine> yeah, that's related to the survey feedback of "more examples with filters"
15:50:41 <samccann> ah cool
15:50:54 * samccann puts 2 n 2 together... infrequently
15:50:54 <acozine> and it would be great to have one
15:51:00 <acozine> that might be a good blog post
15:51:16 <samccann> heh you up for writing one?
15:51:23 <acozine> heh
15:51:34 <acozine> I'm doing a workshop at a conference in two weeks
15:51:37 <samccann> opensource.com is always a good home.
15:51:37 <acozine> ask me after that
15:51:49 <samccann> oh cool
15:51:54 <samccann> anything else begfore we end the meeting?
15:52:29 <acozine> can't think of anything . . . I'm looking at briantist's PR, but we can chat about that during non-meeting time
15:53:13 <samccann> ok that's about it then
15:53:16 <samccann> #endmeeting