15:01:49 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:49 <zodbot> Meeting started Tue Apr  5 15:01:49 2022 UTC.
15:01:49 <zodbot> This meeting is logged and archived in a public location.
15:01:49 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:49 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:49 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:01 <samccann> #topic opening chatter
15:02:10 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:37 <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:03:12 <samccann> briantist: andersson007_ cyberpear around to talk docs today?
15:04:03 <briantist> o/
15:04:28 <ariordan> o/
15:04:35 <samccann> #chair briantist ariordan
15:04:35 <zodbot> Current chairs: ariordan briantist samccann
15:04:48 <samccann> felixfontein: around for docs?
15:05:22 <acozine> o/
15:05:35 * acozine returns from a small kitchen crisis
15:05:43 <samccann> #chair acozine
15:05:43 <zodbot> Current chairs: acozine ariordan briantist samccann
15:05:51 <samccann> ooch hope all is well. no burnt muffins!
15:06:00 <acozine> heh, nothing burnt
15:06:01 * samccann craving muffins
15:06:25 <acozine> just mixed up baking soda and baking powder . . . but caught it in time
15:06:31 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1082155456
15:06:35 <samccann> heh woopsie
15:06:48 <samccann> #topic Documentation Updates
15:06:58 <samccann> Gonna start with the thread going on in the community channel
15:07:12 <samccann> #topic Troubleshooting collection CI problems
15:07:30 <samccann> I've tried to pull out bits and bobs and plop it here - https://hackmd.io/-ahOZc_JSfGjYaK40Nof9w
15:07:55 <samccann> I'm curious if folks think there is a need for some more/better docs about what this collection owner is trying?
15:08:45 <samccann> briantist: bcoca any quick opinions since you both have been working with the collection owner  the past..erm day or so?
15:08:46 <acozine> collection owner?
15:09:09 <samccann> @adhawkins
15:09:30 <acozine> we're talking about using Zuul for release automation?
15:09:33 <samccann> There was the start of a thread on the devel channel and then moved to community channel.
15:09:49 <samccann> Well part of my questions are - is that something we are recommending (and should document)
15:09:58 <acozine> interesting
15:10:01 <briantist> I thought these were sanity errors as opposed to zuul errors?
15:10:45 <samccann> true. What I can't tell is - should a collection owner know how to run sanity tests already? Maybe we just assume everyone knows deep ansible stuff before they become a collection owner.  And maybe that's a wrong assumption
15:11:01 <samccann> So we can take Zuul out of the discussion for now
15:11:03 <acozine> the current document seems to cover two related things - using Zuul for CI on an Ansible collection, and adding automated Galaxy releases to your Zuul setup
15:11:15 <briantist> well, they didn't, got help with that this morning, and now are running sanity, that's where the error is coming from: https://github.com/adhawkins/ansible-borgbase/runs/5833712057?check_suite_focus=true#step:7:280
15:11:50 <samccann> #info our collection development docs may assume a deeper level of ansible experience than actual new collection owners have
15:12:25 <briantist> I'm a little unclear what we're discussing rn 🤔
15:12:30 <samccann> #action - put more troubleshooting breadcrumbs in the docs to point out where/when to run some common ansible-test sanity checks
15:12:34 <samccann> HAHAH
15:12:35 <samccann> sorry.
15:13:02 <acozine> to answer your questions samccann I do think we could do a better job of documenting how to test collections . . . at least, I think that was your question - was it?
15:13:02 <samccann> Let's start with - how did this person get into trouble and what could we add to the docs to help them out?
15:13:25 * acozine BRB, cat howling in the distance
15:13:33 <samccann> #undo
15:13:33 <zodbot> Removing item from minutes: ACTION by samccann at 15:12:30 : - put more troubleshooting breadcrumbs in the docs to point out where/when to run some common ansible-test sanity checks
15:14:04 <samccann> #action put more troubleshooting breadrumbs in the developing/releasing collections to run common ansible-test sanity checks locally first.
15:14:27 <felixfontein> o/
15:14:35 <samccann> #chair felixfontein
15:14:35 <zodbot> Current chairs: acozine ariordan briantist felixfontein samccann
15:14:38 <samccann> welcome!
15:14:38 * acozine is back at desk, cat released from durance vile
15:14:42 <briantist> samccann: well going back to yesterday, where I first started interacting with them, they were trying to use `antsibull-docs` to build collection docs in GitHub actions to publish to GH pages
15:14:56 <briantist> I successfully got them using the docs build stuff (yay!)
15:15:07 <acozine> hooray!
15:15:16 <briantist> and to change their repo layout (collection at the root)
15:15:35 <briantist> later they started adding the automated testing workflows and such, I pointed them at the collection template repo for help there
15:15:37 <felixfontein> briantist: may I ask what layout they used before?
15:15:49 <samccann> ok so they had three things:
15:15:49 <samccann> 1 - generate their own docs pages (using your stuff)
15:15:49 <samccann> 2 - looking for an automated way to publish their collection (where the Zuul recommendation came from)
15:15:49 <samccann> 3 - Basic troubleshooting/tests to run before releasing a collection
15:15:52 <samccann> Does that sound accurate?
15:16:19 <briantist> felixfontein: they didn't have anything before, they appear to be trying to start a collection from scratch based on two modules they wrote
15:16:30 <felixfontein> briantist: ah, so they didn't have a repo yet?
15:17:03 <briantist> they had a repo, and the colelction layout was started in a new branch. The Zuul recommendation came after docs building, they were asking if there was already some GH actions or something to publish to galaxy
15:17:19 <briantist> I mentione dthat included collections already have something so I didn't know of anything else
15:17:34 <briantist> Goneri suggested that anyone could use the Zuul setup and gave instructions for how
15:17:52 <briantist> (this is also something interesting to me for the sqlserver collection I'm helping with)
15:17:55 <samccann> I can ask gundalow if this is something we want to recommend in the future (and in docs)
15:18:15 <felixfontein> (I guess the best first step is getting `ansible-test sanity --docker` working first, to avoid strange errors during the docs build caused by invalid docs ;) )
15:18:24 <samccann> #action samccann - verify if Zuul is available for automating any collection publishing to galaxy
15:18:43 <briantist> the docs build succeeded though! it's kind of weird that sanity failed
15:19:00 <briantist> https://adhawkins.github.io/ansible-borgbase/collections/adhawkins/borgbase/index.html#plugins-in-adhawkins-borgbase
15:19:12 <samccann> validate-modules failed.. Is that part of the docs build? I didn't think so?
15:20:02 <briantist> correct, it's not part of what builds the docs
15:21:22 <samccann> ok thanks everyone for the feedback! I'll figure out where to sprinkle some helpful breadcrumbs in the existing docs for new folks
15:21:40 <briantist> sounds great!
15:21:52 <samccann> dmsimard:  is there an instruqt or some tutorial that walks through building a collection?
15:22:20 <dmsimard> maybe? I'm not sure, /me looks
15:22:30 <samccann> right now the docs don't link to any of those tutorials. Maybe t hey should?
15:22:35 <samccann> s/t/they/, s/hey//
15:22:36 <briantist> if we don't already, pointing at the template is a good idea
15:22:56 <samccann> #action samccann make sure developing collection docs points to the template
15:22:57 <dmsimard> https://www.ansible.com/products/ansible-community-training has "Ansible Community - Creating your own Collection"
15:23:04 <samccann> I think it might but not ssure
15:23:38 <samccann> #action - link to the tutorials at https://www.ansible.com/products/ansible-community-training
15:23:52 <samccann> ok thanks. loads of little action items out of that discussion!
15:24:02 <samccann> anything else on this before we move on?
15:25:13 <dmsimard> https://play.instruqt.com/redhat/tracks/ansible-community-creating-your-own-collection is the link directly to the lab
15:25:59 <samccann> #info tutorial on creating a collection https://play.instruqt.com/redhat/tracks/ansible-community-creating-your-own-collection
15:26:07 <samccann> #topic Ansible docs project board
15:26:17 <samccann> #info - is anyone accessing/using the Docs github project board? is it useful? - https://github.com/ansible/ansible/projects/27?
15:26:34 <samccann> I confess, I barely use it ^^. But I'm wondering if we did use it more, would it be useful to folks?
15:27:08 <samccann> I don't feel like ansible projects get a lot of use out of those boards, but maybe I'm not lookin at the right boards?
15:27:38 <acozine> In the past I've used GitHub boards to track work.
15:27:49 <acozine> I don't currently use that board, though.
15:28:02 <samccann> I have a personal one I use all the time. But it's just my work. Dunno if that would be helpful to anyone
15:28:13 <acozine> though looking at it, there in the Priority Rewrites column I see hte ticket for improving ansible-test docs
15:28:16 <samccann> or if keeping/updating the docs one would be helpful
15:28:22 <acozine> which is relevant to our earlier discussion today
15:28:28 <samccann> heh
15:28:33 <dmsimard> samccann: there's a new project board view that feels better
15:28:35 <samccann> if only we followed the project board!
15:28:35 <dmsimard> trying to find it now
15:28:42 <acozine> he
15:28:45 <acozine> * heh
15:28:52 <samccann> oh I played with that a bit dmsimard
15:29:12 <samccann> I didn't like it for my personal work, but maybe it's better for wide audience project boards like docs.
15:29:18 <dmsimard> samccann: like that: https://github.com/orgs/ansible-collections/projects/6/views/1
15:29:19 * samccann assumes a wide audience for docs heh
15:29:56 <dmsimard> I am also guilty of not using it but the board in itself is not a bad thing
15:30:04 <samccann> heh
15:30:29 <samccann> #info example of a project board using the new format -https://github.com/orgs/ansible-collections/projects/6/views/1
15:30:51 <acozine> in my experience those boards work best if someone organizes them regularly - updating tickets, grooming the various categories/columns, closing tickets, setting priorities
15:31:00 <samccann> I confess - I don't want to create busy-work for myself. If others think they'd pay attention to the docs board if we used it more, I'm happy to do it.
15:31:10 <samccann> I just don't want to do it if I'm the only one looking at it so to speak
15:31:20 <dmsimard> acozine: yes, there are people who are paid to do exactly that :D
15:31:25 <samccann> heh
15:31:39 <samccann> i feel a vote coming on!!!
15:31:46 <acozine> yep, but I don't think anyone is currently paid to do that for the docs board
15:31:57 <felixfontein> sorry, was mostly afk - but now I'm here :)
15:32:01 <samccann> like should we vote on something like "If we had a better docs project tracking board, would you use it?"
15:32:16 <samccann> welcome back felixfontein ;-)
15:33:17 <samccann> ok here we go
15:33:21 * samccann waits
15:34:10 <acozine> honestly, I don't think I would use it - I use the DaWGs agenda to track the things I've said I'll do in Ansible-docs-land
15:34:29 <acozine> or at least, I try to
15:34:35 <felixfontein> since I'm not that much working on docs things (at least not things that will probably be tracked there), I odn't think my opinion is really relevant :)
15:34:37 <samccann> ok let's do this for posterity:
15:34:55 <samccann> VOTE: DaWGS should keep and maintain a better Github project trackign board
15:34:58 <samccann> 1 if you agree
15:35:10 <samccann> -1 if you would never touch it
15:35:14 <samccann> 0 if you think, meh, doesn't hurt
15:35:17 <samccann> :-)
15:35:24 <samccann> #chair
15:35:24 <zodbot> Current chairs: acozine ariordan briantist felixfontein samccann
15:35:29 <felixfontein> 0
15:35:30 <briantist> same as felixfontein , I am generally not working directly on docs things in core, so I doubt I'd ever use it, but would not want it to not exist on my account
15:35:32 <briantist> so `0`
15:35:40 <felixfontein> 0+ maybe ;)
15:35:40 <acozine> agreed, 0
15:35:46 <samccann> heh
15:35:50 <ariordan> 0 also.
15:35:58 <briantist> if even one person would use it, it's worth it imo
15:36:08 <briantist> but I will not be that person ;)
15:36:10 <acozine> I mean, I do some docs stuff but haven't looked at that board in ages
15:36:12 <felixfontein> I agree on that!
15:36:20 <samccann> yeah there is the aspect of 'maybe the powers that be' look at things like that
15:37:02 <samccann> #info - general consensus is that a better project board is not a bad thing, but no one feels they would necessarily use it vs  the existing DaWGs agenda/meeting minutes
15:37:12 <gwmngilfen-work> if the powers that be want to know whats happeneing, they can always come ask me for data ;)
15:37:20 <samccann> HAHAH there ya go
15:37:23 <samccann> ok moving one
15:37:25 <samccann> * ok moving on
15:37:31 <samccann> #topic doctools
15:37:45 <samccann> felixfontein: anything you want to bring up about splitting up `antsibull` ?
15:37:58 <samccann> #info splitting up the antsibull package - https://github.com/ansible-community/antsibull/issues/410
15:38:40 <felixfontein> I'm currently planning to split up antsibull in probably three parts: antsibull-core (some shared code), antsibull-docs (with the antsibull-docs CLI tool), and antsibull (with the antsibull-build and antsibull-lint CLI tools, the latter being deprecated)
15:39:07 <acozine> splitting it up into three repos?
15:39:15 <felixfontein> for users this shouldn't change much, except that if they don't need antsibull-build, they can also just install antsibull-docs in the future and have some less stuff (aka dependencies) coming along
15:39:22 <acozine> or more refactoring within the existing repo?
15:39:27 <felixfontein> the main reason is to separate antsibull-changelog and antsibull-docs more
15:39:38 <samccann> hmm... will any potential users get confused by `core` in one of the names and think it only applies to ansible-core?
15:39:44 <felixfontein> right now antsibull depends on antsibull-changelog (because antsibull-build needs it), but antsibull-docs doesn't need it
15:40:37 <felixfontein> so if we bump the antsibull version for the docs build / sanity test in CI (which is internal to ansible/ansible and not visible in the ansible-core release), we also have to bump the antsibull-changelog version for the changelog sanity test in CI (which is actually visible in collections and thus in the ansible-core release)
15:41:05 <samccann> felixfontein: so with this split, when we need an update to `antsibull-doc` we can do it w/o affecting the test containers?
15:41:09 <felixfontein> bumping something visible has a lot more restrictions, since it's basically a new feature - even if the upgrade has no effect on the changelog sanity test (which it usually has)
15:41:16 <felixfontein> samccann: exactly
15:41:24 <felixfontein> at least without affecting the collections test container
15:41:41 <felixfontein> the ansible-core test container is always affected, since it includes the things needed for the docs build test
15:41:50 <samccann> ah so it might still require container updates for things like the docs-build sanity test?
15:41:57 <samccann> gotcha.
15:42:01 <felixfontein> so this basically allows us to upgrade antsibull-docs internally without affecting something visible in an ansible-core installation
15:42:06 <felixfontein> yes
15:42:13 <felixfontein> but fewer container updates
15:42:18 <felixfontein> (one vs. two)
15:42:19 <samccann> make sense
15:42:25 <samccann> * makes sense
15:42:27 <felixfontein> and it doesn't affect the publicly visible changelog sanity test
15:42:46 <samccann> #info currently planning to split up antsibull in probably three parts: antsibull-core (some shared code), antsibull-docs (with the antsibull-docs CLI tool), and antsibull (with the antsibull-build and antsibull-lint CLI tools, the latter being deprecated)
15:43:23 <felixfontein> one could even split up antsibull a bit more and remove the dependency on antsibull-build on antsibull-docs, but that can be done in a next step - depending on what we learned from the first step :)
15:43:40 <samccann> #info this would mean `antsibull-doc updates would no longer impact the the publicly visible changelog sanity test or the collections test container
15:43:49 <samccann> good stuff, thanks for explaining it all!
15:43:58 <samccann> is there any feedback you are looking for at this point?
15:44:13 <felixfontein> I created a test PR for this, which adds a develop dev dependency on antsibull-changelog to antsibull which would be similar to how it would depend on the new repos (antsibull-core, antsibull-docs)
15:44:30 <felixfontein> I think I'm mainly interested in feedback from developers like briantist and dmsimard :)
15:44:44 <felixfontein> because the splitup should be effectively invisible to most users
15:45:06 <felixfontein> of course if someone else has some feedback, it's also welcome!
15:45:29 <samccann> heh cool
15:45:44 <felixfontein> I guess the main downside for the docs team would be 'more repos in which issues can be opened' ;)
15:45:54 <felixfontein> (or PRs)
15:46:08 <acozine> heh
15:46:08 <briantist> felixfontein: it sounds great to me! I feel slightly unqualified to have thought it through, because I don't have a lot of context on the issues of interactions into core. But I do trust your judgement on it, and the plan sounds forward-thinking and like an improvement to me :)
15:47:03 <samccann> heh that's another problem with the existing docs project board - hard to cover all the other repos with it! Though I do realize it's possible
15:47:09 <acozine> I don't think there are a ton of folks opening issues on antsibull today, are there? I would not expect many docs issues there.
15:47:18 <felixfontein> I think we already discussed splitting up for a longer time, even when Toshio was still around, but never implemented it because it wasn't really urgent. but the necessity of bumping antsibull-changelog in core is a good reason to do it IMO.
15:47:47 <felixfontein> acozine: there are not. also it's easy to move issues between repos in the same organization, so it's not a problem anyway :)
15:48:02 <acozine> I do remember discussions about it, and it seems like a good idea.
15:48:07 <felixfontein> it could mostly be a little bit confusing if you're searching for an issue and cannot find it because you look in the wrong repo
15:48:51 <samccann> yeah I think so long as docs are in ansible/ansible, there will be the odd issue or two opened up about something that's actually in the theme or in `anstibull-docs`
15:49:02 <samccann> but I don't see that happening much
15:49:32 <samccann> ok we have 10 minutes left to open the floor
15:49:35 <samccann> #topic Open Floor
15:50:10 * samccann feels that has a strange sort of history to it..parliamentary procedure or something?
15:50:26 <samccann> Here's the time to bring up anything you want about docs!
15:50:37 <bcoca> planning on adding no_log to docs (already present in argspec)
15:50:42 <felixfontein> I've already created new repos (https://github.com/ansible-community/antsibull-core, https://github.com/ansible-community/antsibull-docs) and will start filling them with content to see how things work. once I got something that looks promising I'll do more pings :)
15:50:50 <felixfontein> bcoca: awesome!
15:50:55 <bcoca> do i keep no_log name or should we have confidential/secret/etc?
15:51:12 <felixfontein> bcoca: what's the status of the sidecar PR? will it be merged early in the next development phase?
15:51:19 <acozine> I updated https://github.com/ansible/ansible/issues/75509 with a checklist of CLI commands to add cheatsheet entries for.
15:51:27 <bcoca> felixfontein: i wish i knew
15:51:42 <acozine> and checked off `ansible-playbook` now that PR 76655 is merged
15:52:04 <samccann> Thanks acozine !!
15:52:31 <acozine> bcoca: I could see the argument either way - `no_log` has a long history and experienced folks know it
15:52:46 <samccann> bcoca: realizing I know zero about this - but 'secret' has a security implication so I'd avoid that
15:53:08 <acozine> also `no_log` describes what the feature actually does
15:53:12 <felixfontein> 'censor' might also be another name for it
15:53:14 <samccann> does no_log mean just... no logging?
15:53:26 <felixfontein> because that's basically what it does, it will censor that value in any output (log or return value)
15:53:32 <gwmngilfen-work> "redact" is also an option?
15:53:35 <bcoca> samccann: no_log has security implication
15:53:39 * gwmngilfen-work is a thesaurus
15:53:45 <acozine> it means "don't put this into the log because the output will contain secrets/passwords"
15:53:46 <felixfontein> gwmngilfen-work: 'redact' sounds better than 'censor' :)
15:53:57 <acozine> heh, agreed
15:53:59 <bcoca> gwmngilfen-work++ on redact
15:54:04 <acozine> censor is so . . . censorious
15:54:12 <bcoca> redacted: true
15:54:13 <gwmngilfen-work> censor implies judgement ;)
15:54:37 <samccann> redact might work, but I agree with acozine comment - if there is already a `no_log` feature, we would need a compelling reason to change the name
15:55:29 <felixfontein> there are two different (but related) no_log features in Ansible
15:55:44 <acozine> the other argument in favor of the change (or the addition) would be that `redacted: true` is easy to read - easier in my mind than `no_log: true` which always takes me a few seconds to parse . . .
15:56:05 <acozine> I think "wait, do i set this to `true` or to `false`? and then I have to think through the logic
15:56:09 <felixfontein> also just because it's called `no_log` in YAML doesn't mean it couldn't be shown as `redacted` in the HTML version :)
15:56:38 <felixfontein> though it will be confusing if different help display programs show that value differently
15:56:42 <bcoca> can also just have both, one as alias to other ...
15:57:23 <gwmngilfen-work> acozine: indeed, double-negatives aren't great (i.e no_log: false)
15:57:30 <felixfontein> bcoca: that makes the doc display world more complicated :)
15:57:55 <bcoca> felixfontein: more worried about user comprehension than the complexity of code they'll never read
15:58:37 <felixfontein> bcoca: I'm worried about both ;)
15:58:50 <samccann> `redacted: false` vs `no_log: false`
15:58:59 <felixfontein> anyway, I have to switch to the more important questions in life - what do I cook for today's dinner?
15:59:07 <samccann> lol
15:59:17 <samccann> whatever it is, ya gotta share the recipe!
15:59:20 <samccann> ;-)
15:59:28 <bcoca> felixfontein: i already have my lunch planned, creamy fetuchini with spinach
16:00:08 <samccann> so +1 for `redacted` with a `no_log` alias from me
16:00:25 <samccann> and +1 for bcoca sharing lunch w the rest of us cuz that sounds tasty
16:00:41 <samccann> We're at the top of the hour. Anything else before we end the meeting?
16:00:42 <felixfontein> bcoca: I'll probably do some kind of curry... I have enough fitting fresh veggies for that
16:00:50 <bcoca> i have still not solved the PoIP issue (pasta over internet protocol)
16:00:59 <felixfontein> but yeah, a bite of bcoca's lunch also sounds good :D
16:00:59 <briantist> I just placed my lunch order, after not being able to decide for 45 minutes (so, regular day really)
16:01:05 <bcoca> felixfontein: i have some fresh asparragus also as salad
16:01:08 <samccann> hahaha
16:01:25 <samccann> should have started this with topic food plans
16:01:34 <felixfontein> ok, I'm off to the kitchen now. see you later ;) and enjoy your food! :)
16:01:37 <samccann> #endmeeting