15:00:38 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:38 <zodbot> Meeting started Tue Sep  7 15:00:38 2021 UTC.
15:00:38 <zodbot> This meeting is logged and archived in a public location.
15:00:38 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:38 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:38 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:00:55 <samccann> #topic opening chatter
15:01:04 <samccann> so who's around to talk the docs today?
15:01:57 <ariordan[m]> I'm here
15:02:00 <samccann> andersson007_ dericcrago dmsimard gundalow ariordan briantist cyberpear felixfontein mrproper[m] Xaroth you folks chatting docs today?
15:02:02 <samccann> woo hoo!
15:02:12 <briantist> o/
15:02:13 <samccann> #chair ariordan[m]
15:02:13 <zodbot> Current chairs: ariordan[m] samccann
15:02:20 <samccann> #chair briantist
15:02:20 <zodbot> Current chairs: ariordan[m] briantist samccann
15:02:24 <samccann> Welcome welcome!
15:02:25 * gundalow waves
15:02:30 <samccann> #chair gundalow
15:02:30 <zodbot> Current chairs: ariordan[m] briantist gundalow samccann
15:04:08 <samccann> Ok while we see if others might be coming in later...
15:04:13 <samccann> #topic introductions
15:04:22 <gwmngilfen-work> o/
15:04:59 <samccann> #info today we have a new RH writer coming in to help us in DaWgs land - ariordan[m].
15:05:35 <gundalow> ariordan: Welcome :)
15:05:36 <samccann> You'll see her in and around docs PRs, merges, and discussions here over time so please make her welcome to are intrepid little group!
15:05:41 <gwmngilfen-work> welcome ariordan :)
15:05:44 <ariordan[m]> Thank you!
15:05:51 <briantist> welcome ariordan[m] !
15:06:05 <samccann> #chair gwmngilfen-work
15:06:05 <zodbot> Current chairs: ariordan[m] briantist gundalow gwmngilfen-work samccann
15:06:38 <samccann> Just to explain to any newcomers - We 'chair' or turn people into furniture here during the meeting to allow anyone to add important items to the meeting minutes
15:06:40 * dericcrago waves
15:06:48 <samccann> #chair dericcrago
15:06:48 <zodbot> Current chairs: ariordan[m] briantist dericcrago gundalow gwmngilfen-work samccann
15:07:06 <samccann> So for example, now dericcrago can type #info just a test
15:07:37 <samccann> and 'just a test' will show up in our meeting minutes. Useful commands are #info, #agreed, #action, etc. See the start of the meeting for a list
15:08:04 <samccann> Meanwhile, our Agenda this week starts at https://github.com/ansible/community/issues/579#issuecomment-909629613
15:08:11 <samccann> #topic action item review
15:08:35 <samccann> aaand the part of the meeting I'm starting to dread... feel like I should call it 'things I thought I'd get to but didn't yet' :-)
15:08:57 <gwmngilfen-work> i should show you my todo list ...
15:09:21 <samccann> heh.
15:09:40 <samccann> #info - samccann didn't get to any of her action items yet so  they remain on the list this week
15:10:24 <samccann> With that, we can morph into the discussion items for this week
15:10:50 <samccann> #topic search improvements
15:11:38 <samccann> So last week we mentioned that we'd fiddled a few knobs on the docs.ansible.com/ansible search engine to make it better. We asked folks to use the embedded search and report back with what they thought - any better? any worse? Places we still need to improve?
15:12:56 <samccann> did anyone give it a try?
15:14:23 <samccann> :-) Okay maybe folks can start using it this week and let us know?
15:14:38 * gwmngilfen-work hides
15:14:40 <abadger1999> good morning
15:14:45 <samccann> morning!
15:14:52 <samccann> #chair abadger1999
15:14:52 <zodbot> Current chairs: abadger1999 ariordan[m] briantist dericcrago gundalow gwmngilfen-work samccann
15:15:12 <samccann> and good timing, let's hop onto the next topic
15:15:37 <samccann> #new plugin attributes
15:16:05 <samccann> #info details on attributes - https://hackmd.io/R71WLQjPQOa-Ze0Cg97V7A and PR - Attributes compat ansible#75563
15:16:39 <samccann> abadger1999 felixfontein - I've lost the plot on where we are with these?
15:16:43 <samccann> do you know?
15:16:58 <abadger1999> So, I think there's two things for next steps here.
15:17:38 <abadger1999> (1) Need to mock up what we want the collection docs pages that display collections  look like (probably a plugin page and a list of all attributes)
15:18:09 <abadger1999> (2) Need to get changes made to the attributes so that we can only display attributes which differ from their default setting on the plugin page itself.
15:19:09 <abadger1999> If (2) can't be done in time, then maybe we need to revert changes to the plugin docs in ansible-core which removed the documentation which is duplicated by the attributes.
15:20:02 <samccann> #info next steps - (1) Need to mock up what we want the collection docs pages that display collections  look like (probably a plugin page and a list of all attributes)
15:20:12 <samccann> #info (2) Need to get changes made to the attributes so that we can only display attributes which differ from their default setting on the plugin page itself.
15:20:13 <ariordan[m]> cyb-clock-clone says we are 20 minutes into the meeting
15:20:25 <samccann> :-) thanks ariordan[m]
15:21:17 <samccann> ok so we made the decision then that only non-default attributes get displayed?
15:22:06 <samccann> #info If (2) can't be done in time, then maybe we need to revert changes to the plugin docs in ansible-core which removed the documentation which is duplicated by the attributes.
15:22:24 <abadger1999> we didn't vote on it, but it seemed like consensus amongst docs people
15:23:32 <abadger1999> do we want to vote now?
15:23:44 <samccann> okay so maybe the best thing is a quick mockup (#1) with and without default settings to see what it looks like? I'm thinking something manual like we just create foo_module.rst file manually and see what it looks like? (aka not coding it up yet)
15:23:51 <abadger1999> <nod>
15:24:27 <samccann> #action samccann ariordan[m] work with abadger1999 to create dummy plugin rst pages to see what attributes might look like
15:25:20 <samccann> So what is our  timeline here? We need anything that might be code inside ansible/ansible done within a couple of weeks right? Isn't core feature freeze coming soonish?
15:25:31 <abadger1999> Yeah.
15:25:50 <abadger1999> note that there's other things which are breaking docs build which I believe require core changes too.
15:26:16 <samccann> core feature freeze is 9/24
15:26:28 <samccann> ok let's move onto that topic then
15:26:39 <samccann> #topic - things breaking the docs build
15:26:43 <samccann> can you elaborate?
15:27:03 <abadger1999> I made a list a while ago and passed it on.  Let's see if I can find it.
15:27:12 <samccann> thanks :-)
15:27:54 <abadger1999> == command line arguments being added to the config subsystem which reads out of documentation ==
15:27:54 <abadger1999> https://github.com/ansible/ansible/pull/73708
15:28:31 <samccann> #info command line arguments being added to the config subsystem which reads out of documentation https://github.com/ansible/ansible/pull/73708
15:29:13 <abadger1999> Okay, the other prs are known or reverted.
15:29:36 <abadger1999> There are some PRs in progress that I don't know if they're destined for this release of ansible-core or hte next one, though.
15:29:44 <abadger1999> == docs in side car ==
15:29:44 <abadger1999> https://github.com/ansible/ansible/pull/74963
15:29:52 <abadger1999> == adding mutually_exclusive, required_if, and other arg spec modifiers ==
15:29:56 <abadger1999> https://github.com/ansible/ansible/pull/74873
15:30:07 <abadger1999> (I think they want this added to this release)
15:30:11 <samccann> #info docs in side car https://github.com/ansible/ansible/pull/74963
15:30:16 <abadger1999> == semantic markup ==
15:30:29 <samccann> #info adding mutually_exclusive, required_if, and other arg spec modifiers https://github.com/ansible/ansible/pull/74873
15:30:35 <abadger1999> (This is the change we have approved but core/others have not)
15:30:56 <abadger1999> * ansible-core portion: https://github.com/ansible/ansible/pull/74937    antsibull portion: https://github.com/ansible-community/antsibull/pull/281
15:31:11 <samccann> #info semantic markup (approved by docs, but not other impacted teams like core, galaxy-ah etc) - ansible-core portion: https://github.com/ansible/ansible/pull/74937    antsibull portion: https://github.com/ansible-community/antsibull/pull/281
15:32:22 <abadger1999> I think that's it (note: I'm not looking for htese things actively... these just crossed my path at one time or another)
15:32:31 <samccann> ok can we elaborate on the others (not semantic markup since that one is ours so to speak) . What's the doc impact on each? Or is it better to just write it all in a hackmd to track it?
15:32:57 <samccann> or a github issue and link to each?  not sure the best approach but we are running short on time until the freeze so these are feeling like priority items now
15:33:13 <abadger1999> command line args breaks the ssh connection plugin.  Last I talked to him, nitzmahone thought it should be reverted.
15:33:21 <abadger1999> I haven't heard anything further on it in months
15:34:00 <samccann> #info command line args breaks the ssh connection plugin, might need to be reverted (or fixed) . Followup with nitzmahone
15:34:20 <abadger1999> docs in side car I haven't heard anything... I'd hope that core would discuss it with the docs team so that we could have a poc at the same time, before the pr is merged to core.
15:34:45 <samccann> #action samccann to create a master list of these priority items impacting the docs to raise visibility on what needs to happen with only 2.5 weeks till core freeze
15:34:49 <abadger1999> (that way we won't find ourselves in the situation we have with attributes right now where the thing that got added to core is insufficient)
15:35:17 <ariordan[m]> cyb-clock-clone says we are 35 minutes into the meeting
15:35:57 <samccann> okay so docs-in-side-car doesn't 'work' on its own with that PR? it needs either more core work or work in antsibull?
15:36:57 <abadger1999> I do not know since I haven't heard anything baout it from core.  I just saw the PR in a list at one time.
15:37:16 <samccann> ok thanks for keeping an eye on things! I'd never even have noticed it
15:37:50 <abadger1999> It could be that the structure wil conform to the existing schema and the speific code that we use from ansible-core will hide the implementation detail from us.  But I don't know that for sure.
15:38:42 <abadger1999> But it could also be that there are differences in there that will be surfaced once we discuss it or try to implement using it.
15:39:18 <samccann> ok
15:39:40 <samccann> for the validate-modules one, I put a comment on the PR just now to see if he is targeting this for 2.12
15:39:59 <samccann> sorry, mutually-exclusive PR ^^
15:40:20 <abadger1999> <nod>
15:40:45 <abadger1999> I believe that the content team would like it for 2.12.  It's just more work than they anticipated when they originally opened the issue.
15:40:54 <samccann> yeah
15:41:05 <samccann> Since we are talking 2.12...
15:41:16 <samccann> #topic Things we need done for 2.12
15:41:47 <samccann> Are there any other things on our collective and vast todo lists that we really need done by either the core feature freeze (9/24) or by core release?
15:43:23 <gwmngilfen-work> samccann: this is separate to the content freeze you warned me about last week?
15:43:37 * gwmngilfen-work wonderss if he suddenly has more time to write matrix docs
15:43:43 <samccann> oh if only I could remember what I was talking to you about last week
15:43:51 * gwmngilfen-work scrolls up a bit
15:43:57 <samccann> ooo yeah you do have more time for matrix docs. That was just a minor release freeze
15:44:23 <samccann> #info gwmngilfen-work has more time to polish up matrix docs
15:44:27 * gwmngilfen-work will find time for it this week then
15:45:08 <samccann> in general, we can fix the docs all the time. It's just we can't merge backports for a week every month or so.
15:45:10 <gwmngilfen-work> sorry for sidetracking
15:45:23 <gwmngilfen-work> got it 👍️
15:45:46 <samccann> But we couldn't backport the matrix docs themselves anyway because it touched files where we didnt backport some other set of PRs etc (aka a chain of backports). So it's only available in devel until 2.12 releases
15:46:43 <samccann> no worries. This is why I wanted to talk a bit about the 2.12 and Ansible 5 releases. We are one-brain down here (aka sniff... acozin) so I need to start writing things down, tracking the priorities etc so nothing important slips through the cracks
15:47:48 <samccann> okay I'm going to sneak in one more topic before we open the floor
15:48:47 <samccann> #topic rendering docs in collections at the PR level
15:49:12 <samccann> briantist - I feel like you've been doing a ton of work and we haven't raise the visibility of it well enuf yet.
15:49:28 <briantist> some small docs build updates:
15:49:28 <briantist> I've updated my build process to show diff output in an expandable box in the PR comment. Demo PR (reviews on content welcome too!): https://github.com/ansible-collections/community.hashi_vault/pull/139
15:49:29 <briantist> I've also started documenting some of the existing functionality and details in an issue (it'll find a better home later). A lot of this is dedicated to explaining the somewhat confusing, tricky, and potentially dangerous `pull_request_target` event needed in GitHub actions: https://github.com/ansible-collections/community.hashi_vault/issues/138
15:49:39 <briantist> (I had that pre-typed for open floor lol)
15:49:56 <samccann> #info briantist has a way to render docs from a collection PR
15:50:11 <samccann> #info show diff output in an expandable box in the PR comment. Demo PR (reviews on content welcome too!): https://github.com/ansible-collections/community.hashi_vault/pull/139
15:50:13 <briantist> but yeah.. some incremental changes, but at least starting to get some of it out of my head and dumped into text, in that issue, #138
15:50:25 <gwmngilfen-work> do we need more visibility? should this be a bullhorn thing?
15:50:26 <samccann> #info documenting some of the existing functionality and details in an issue (it'll find a better home later). A lot of this is dedicated to explaining the somewhat confusing, tricky, and potentially dangerous `pull_request_target` event needed in GitHub actions: https://github.com/ansible-collections/community.hashi_vault/issues/138
15:50:44 <ariordan[m]> cyb-clock-clone says we are 50 minutes into the meeting
15:51:25 <briantist> I'm still struggling with some of the boundaries on this stuff, how to share with others/make it generalizable. felixfontein had mentioned wanting it on the collections he maintains but is also short on time
15:51:27 <samccann> it's definitely something people want. Someone on an ansible mailing list recently talked about this difficulty, but I didn't know how to answer them in terms of what briantist has been doing
15:51:57 <gwmngilfen-work> briantist: what would you like? it's your work 🙂
15:52:01 <briantist> I think we will start working on one of his, and I suspect a lot of important stuff will fall out of trying to implement it elsewhere that will go a long way
15:52:19 <briantist> I think it's premature to send it to the bullhorn or a wider audience at this time :)
15:52:31 <samccann> :-) ok cool.
15:52:40 <gwmngilfen-work> fair enough :)
15:52:41 <briantist> but I'm happy to keep sharing updates in this WG, and moving things along
15:52:50 <samccann> great, thanks!
15:52:53 <gwmngilfen-work> since it's open floor, do you want the new reminderbot in here? might save you a minor amount of work doing meeting announcements :P
15:53:01 <samccann> #topic Open Floor
15:53:02 <briantist> and it's all open for anyone to look at directly or experiment with and I'm around to help with it and explain
15:53:03 <samccann> go for it
15:53:17 <samccann> what is the reminderbot?
15:53:24 <gwmngilfen-work> i just realised it could be used for in-meeting cyb-clocks too :P
15:53:39 <gwmngilfen-work> example!
15:53:42 <briantist> samccann: can you link me to the mailing list comment?
15:53:58 <gwmngilfen-work> !remind in 1 min; test
15:54:05 <gwmngilfen-work> (bot is in utc)
15:54:19 <gwmngilfen-work> you can also use exact times, and do recurring reminders
15:54:48 <gwmngilfen-work> docs: https://github.com/anoadragon453/matrix-reminder-bot
15:54:52 <samccann> briantist - https://groups.google.com/g/ansible-devel/c/dXiXstYtis4/m/MZPw_alzBwAJ
15:54:57 <remindbot[m]> <a href="https://matrix.to/#/@gwmngilfen:ansible.im">@gwmngilfen:ansible.im</a> test
15:55:00 <samccann> looks like felixfontein gave them some help
15:55:22 <briantist> thanks!
15:55:41 <samccann> #info remind bot can give little reminders, for example !remind in 1 min; test
15:55:58 <samccann> oh remindbot in irc looks... messy
15:56:18 <samccann> does it look neater in matrix?
15:56:18 <gwmngilfen-work> yeah, it messes up usernames, there is an open issue
15:56:33 <gwmngilfen-work> it does, i can screenshot if you like :)
15:56:38 <samccann> hah sure
15:56:42 <gwmngilfen-work> samccann: i think what you probably want is this:
15:56:44 <gwmngilfen-work> !remind every 1w; tuesday at 14:00; DING DING DING!  DaWGs (documentation working group meeting) happening in 1 hour
15:56:59 <gwmngilfen-work> oh darn
15:57:06 <gwmngilfen-work> thats not a room alert
15:57:31 <gwmngilfen-work> !cancelreminder !remind DING DING DING!  DaWGs (documentation working group meeting) happening in 1 hour
15:57:42 <gwmngilfen-work> not my day. do you want this in the logs? :P
15:57:48 * gwmngilfen-work will fix
15:57:55 <samccann> #info to cancel a reminder !cancelreminder !remind test
15:57:58 <gwmngilfen-work> !listreminders
15:58:11 <samccann> #info to list reminders !listreminders
15:58:20 <gwmngilfen-work> !cancelreminder every 1 week; next run in 6 days; "DING DING DING! DaWGs (documentation working group meeting) happening in 1 hour"
15:58:27 <gwmngilfen-work> grr
15:58:28 <samccann> it's interesting. We can play with it some later
15:58:35 <gwmngilfen-work> i will set this up
15:58:44 <gwmngilfen-work> but i will also stop hogging the floor
15:58:54 <samccann> Any other open floor items?
15:58:59 <gwmngilfen-work> (I know cybette set it up for the community wed meeting, just have to get it right :P)
15:59:13 <samccann> This is the time in the meeting where you can bring anything docs related up for discussion.
15:59:27 <samccann> got a fav PR? Issue? here's your time~
16:00:05 <abadger1999> :-)
16:01:41 <samccann> ok not hearing much so gonna end this meeting unless someone screams soon
16:02:12 <samccann> #endmeeting