15:02:29 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:02:29 <zodbot> Meeting started Tue Aug 30 15:02:29 2022 UTC.
15:02:29 <zodbot> This meeting is logged and archived in a public location.
15:02:29 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:02:29 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:02:29 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:56 <samccann> lol now I think I sent everyone off to make tea!
15:03:00 <samccann> #topic opening chatter
15:03:18 <samccann> #chair Don Naro
15:03:18 <zodbot> Current chairs: Don Naro samccann
15:03:18 <DonNaro[m]> hello, hello
15:03:18 <samccann> welcome welcome!
15:03:19 <DonNaro[m]> hi acozine
15:03:26 <briantist> o/
15:03:34 <samccann> @room Meeting time! Who is here to talk the docs?
15:03:54 <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:54 <DonNaro[m]> as usual I'm double booked but am around
15:04:05 <samccann> heh you need to clone yourself!
15:04:23 <samccann> briantist: felixfontein around to talk docs today?
15:04:45 <briantist> hm, I already raised my hand, is this another matrix/IRC delay situation :(
15:04:55 <samccann> #chair briantist
15:04:55 <zodbot> Current chairs: Don Naro briantist samccann
15:04:56 <DonNaro[m]> samccann: I've got kids but child labour laws are pretty strict here so...
15:05:08 <izzycious[m]> HI, new folk and i am still going through the docs to understand
15:05:09 <samccann> ah well. We'll live with 1/2 of you for today ;-)
15:05:09 <DonNaro[m]> hi izzycious
15:05:52 <samccann> #chair izzycious
15:05:52 <zodbot> Current chairs: Don Naro briantist izzycious samccann
15:05:53 <samccann> Welcome!  Everyone gets to be chair here!
15:06:31 <samccann> That gives everyone the opportunity to add notes to the meeting minutes for example. Just start the sentence with #info
15:07:24 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1216847049
15:07:38 <samccann> #topic Action Item updates:
15:07:44 <samccann> These came from last week's meeting:
15:07:46 <samccann> #info resolved - Collectionw SHOULD use boolean true/false in examples. (aka it's not a MUST)
15:08:40 <acozine> o/
15:08:40 <samccann> so that was an open question last week -whether we insist everyone use true/false or not in their collection examples. The result is no, we don't want to make it mandatory.
15:08:53 <samccann> #chair acozine
15:08:53 <zodbot> Current chairs: Don Naro acozine briantist izzycious samccann
15:09:10 <samccann> did you make tea for all of us? :-)
15:09:24 <acozine> heh, if I could pass out tea over the internet, I would!
15:09:25 <acozine> lemon ginger today
15:09:37 <samccann> yum!
15:09:37 <acozine> hi and welcome izzycious
15:09:47 <samccann> #info open - Create tracking issue 'somewhere' to track all the collections that SHOULD consider using true/false boolean in examples (tho some may not want to for $REASONS)
15:10:19 <acozine> heh, zodbot is a bit behindhand today
15:10:40 <samccann> on of these days/weeks, I'll just need to sit and create a ton of collection issues. I have a backlog now!
15:11:33 <acozine> yeah, that's the downside of distributed collections - lots of repos to track
15:11:42 <samccann> yep
15:12:22 <samccann> #info open - if https://github.com/ansible/ansible/pull/78561 will be completed by 2.14 freeze (booleans in ansible-doc output).
15:13:05 <samccann> That one is bcoca pr that I think will allow `ansible-doc` to show whatever boolean is used in the code...but I could be wrong :-) It is associated with booleans tho
15:13:52 <samccann> #info resolved - the remaining sidecar docs work should be completed this week, so we should be okay to get CI updated to use the most recent antsibull-docs versions soon (before 2.14 branch pull)
15:15:13 <samccann> I'm on PTO next week, so that may not happen until Sept 12, but early testing sez everything works right now. I'll try it again and have a WIP PR in place that we can fire off on that Monday if all goes well
15:15:13 <acozine> wow, that's a big step forward
15:15:53 <samccann> #action samccann create WIP PR to update docs CI test requirements ready for merging aorund Sept 12
15:16:12 <samccann> Ok that's my list of action items
15:16:19 <samccann> Anyone else tracking any action items before we move on to the next topic?
15:16:49 <samccann> cool
15:16:49 <acozine> not that I remember
15:16:50 <samccann> #topic Documentation updates
15:17:04 <samccann> #info archiving 2.3 docs -waiting on Jenkins help to define the output path. They will be available from docs.ansible.com/archive.
15:18:23 <samccann> So to elaborate, our docs are published through a Jenkins job. That job today sets a couple of variables for nightly builds vs production builds. We know how to add a couple for the archive builds, but want to get it embedded 'whereever' the other two are defined.  Which we can't see anymore cuz they changed Jenkins permissions a bit back.
15:19:12 <samccann> We could probably just hack it into the actual jenkins job we're using, but you know, trying to play by the rules first :-)
15:20:10 <samccann> #info Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
15:20:10 <samccann> #info Help on issues always welcome :-)
15:20:29 <samccann> Don Naro:  if you are around - any updates on user guide fun? We're in the last couple of weeks to complete the big moves
15:20:33 <samccann> well, actually, we could keep going after branch pull, but that means more backports.
15:21:18 <DonNaro[m]> samccann: we're close but I've been delayed by PTO. fingers crossed I can get the rest of the PRs this week or early next week.
15:21:27 <samccann> coolness
15:21:27 <acozine> Don Naro: I did some editing on the Intro to Inventory page, I think it could be split into 2 or 3 files now pretty easily
15:21:44 <acozine> One on Inventory Basics, one on Inventory Variables, and one for whatever else is in there
15:22:38 <DonNaro[m]> acozine: great! I hope to do some more editing on the actual content after we get the User Guide all split out. that sounds like a good start.
15:23:20 <DonNaro[m]> I had to hold myself back from making too many changes to the actual content. there's still so much to do there to improve content org.
15:23:34 <DonNaro[m]> not to mention dropping some out of date content
15:24:07 <DonNaro[m]> acozine: please do feel free to add me to the PR too!
15:24:47 <acozine> Don Naro: it's merged already: https://github.com/ansible/ansible/pull/78634
15:25:43 <DonNaro[m]> that's a pretty sweet PR. nice one acozine
15:25:58 <acozine> thanks!
15:26:33 <samccann> always great when someone finds an area of confusion in the docs and just goes in and fixes it! Kudos!
15:26:56 <samccann> #info Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
15:26:56 <samccann> #info Help on issues always welcome :-)
15:27:39 <samccann> #info - if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.
15:27:51 <samccann> #topic doctools
15:27:59 <samccann> #info including collection-level changelogs into docs.ansible.com - https://github.com/ansible-collections/community.hashi_vault/pull/299
15:28:02 <samccann> #info with example output at https://ansible-collections.github.io/community.hashi_vault/pr/299/collections/community/hashi_vault/index.html
15:28:40 <briantist> this one is pretty straightforward I think, but happy to expand on anything :)
15:28:41 <samccann> briantist: WIP there.
15:28:53 <samccann> Gist of it is - we could include changelogs on docs.ansible.com to go with each collection (that opts into this).
15:30:04 <briantist> it's only marked WIP in that I wanted to get feedback about it, but the change as is, is very small and easy
15:30:08 <samccann> two things come to mind (other than I like this idea :-)
15:30:29 <briantist> 🍿👀
15:30:48 <samccann> 1 - will we get into problems if say a `community.general` changelog shows up with ALL the versions like this one has.
15:30:50 <samccann> as in, will the HTML get super long and cause some kind of problem?
15:31:54 <acozine> that's a really useful addition briantist
15:32:08 <zbr> felixfontein: are you working or plan to work on the booleans thing by any chance?
15:32:18 <briantist> 1 - my guess is no, that there will be no problem with a very long changelog, at least not from an HTML standpoint. But a similar PR could be put up on c.g by anyone, and the docs build in the PR will give us a rendered version to find out :)
15:32:29 <briantist> thanks acozine !
15:32:51 <acozine> heh
15:32:57 <samccann> heh good to know!
15:32:57 <acozine> if it got too long, could we limit it to changes from the current release?
15:33:35 <samccann> Well we don't control the page it points to acozine
15:33:55 <samccann> tho we can 'advice'
15:33:56 <acozine> as in, that rendered page describes the hashivault collection version  3.3.0
15:34:16 <acozine> ah, is that changelog page being created anyway?
15:34:17 <acozine> pj. ot
15:34:17 <samccann> yep. it lives in each collection repo
15:34:18 <acozine> * oh, it's on GitHub
15:34:28 <briantist> right, that changelog is typically generated by `antsibull-changelog` and I don't think we'd _want_ to truncate that even if it has the ability. Perhaps a new workflow where a full and truncated version are generated?
15:34:28 <acozine> so all we're adding is a link
15:34:50 <briantist> technically not just a link, the RST version will be rendered to HTML
15:35:01 <samccann> a link that then pulls in whatever is AT that link into the docs build and output as HTML
15:35:22 <acozine> it does?
15:35:47 <acozine> okay, maybe I should have made coffee instead of herbal tea
15:35:48 <samccann> heh
15:36:10 <briantist> well, it's not a link that does that, the docs generation process does it, just as it does for other RST files in the docsite
15:36:36 <briantist> I'm just symlinking it into the docsite so that it's in a place that the extra-docs feature can read it
15:36:42 <samccann> ok so it 'may' be a problem for a super long RST, but my guess is something would break and we'd notice it.
15:36:51 <samccann> but I have a bigger fear
15:37:08 <briantist> I can't say for sure, but I doubt the length of any changelog we have would cause a problem
15:37:17 <briantist> what's the bigger fear?
15:37:28 <samccann> #2 - what stops a disgruntled collection owner from adding an rst link like this does, but pulls in RST porn or something?
15:37:43 <samccann> #2 is more a general fear, not realated to changelogs etc
15:38:02 <samccann> So let's say we told foo.bar collection owner that they are getting the boot due to no real maintenance.
15:38:37 <samccann> and 'on the way out hte door' they put in one last PR to the existing collection, with an extra link to an RST file that says' ALL ANSIBLE SHOULD ROT IN HELL' etc
15:38:45 <briantist> there's no new risk of that, anyone could already do that now
15:38:54 <samccann> we would never know until someone in community saw it and said what the heck Ansible??
15:38:54 <briantist> anyone == any collection maintainer
15:39:12 <briantist> as maintainers we already control the docsite / extra-docs feature
15:39:31 <samccann> yeah that's my point briantist - it's not a new risk, it's an existing risk because the extra-links functionality has no checks on it (other than presumably it has to be functional RST)
15:40:21 <briantist> I would think that the risk of pushing malware/malicious code is a much higher risk, and we've already decided to trust those maintainers with that
15:40:44 <samccann> maybe I should ask the community team this one. I don't want to fear-monger. I suppose a collection owner can put in anything at any point (including in the python docstrings that say bad things).
15:40:47 <briantist> but anyway, the docsite/extra-docs feature has been around for a while, so that concern should probably be brought up as a separate issue I think
15:41:31 <samccann> yep
15:42:36 <briantist> what I was most interested in is whether there's appetite to make "changelog in the docsite" a first-class feature of the docs tools
15:42:49 <briantist> like you could easily opt in to it, without needing to make a symlink
15:42:53 <samccann> omgosh 3 dogs just now barking like the world is coming to an end. All because the poor mail delivery person came to the wrong door
15:43:03 <briantist> but given how easy this is, maybe the effort is not worth it?
15:43:17 <samccann> yeah seems very easy the way it is now briantist
15:43:55 <samccann> I'd say the reason perhaps to make it 'first class feature' would be if we did want to put some CI against it for $REASONS
15:44:46 <samccann> but today, we don't have CI for any of the changelogs outside of core (and not sure what core does?)
15:45:13 <samccann> tho maybe anstibull-changelogs already has something in it that.. does... some kind of testing/validating? dunno
15:45:13 <briantist> that reminds me, I have been meaning to add a CI check for changelog fragments; I've done it in local/private repos
15:45:25 <briantist> it doesn't enforce their existence, just lints them if they exist
15:45:34 <briantist> preventing bad fragments from getting merged
15:45:34 <samccann> :-)
15:45:54 <briantist> yeah, it already has a linting feature
15:46:02 <samccann> yeah that's a reasonable level of testing
15:46:15 <briantist> but, it is rather separate from this discussion too
15:46:26 <briantist> those bad fragments would have fialed on the changelog generation process anyway
15:46:34 <briantist> so they never would have gotten into the changelog.rst
15:46:35 <samccann> yeah so feels to me like using extralinks for this like your PR does is good enuf
15:46:48 <samccann> but might be worth bringing up with felixfontein or other collection owners for their opinions
15:47:02 <samccann> yeah feels like that's where the validation belongs.
15:48:44 <samccann> ok we have a few minutes left...
15:48:48 <samccann> #topic Open Floor
15:48:48 <briantist> yeah would like to get Felix's thoughts and anyone else who's interested
15:48:54 <briantist> but yeah, we can move on from this now :)
15:49:03 <samccann> :-)
15:49:17 <samccann> I'm +1 for sure. Think it's a great addition
15:49:33 <samccann> meanwhile, anyone have anything else docs related they want to bring up? Here's your chance!
15:49:56 <acozine> yeah, I think there has to be a level of trust involved
15:49:59 <acozine> already, I mean
15:50:08 <acozine> we can't prevent everything
15:50:35 <acozine> sorry, got distracted, responding to conversation above about "revenge docs"
15:50:54 <acozine> I failed to scroll down before typing
15:51:13 <samccann> omgosh revenge docs!!! hahah perfect
15:53:15 <samccann> ok not hearing anyone have anything else before we end the meeting?
15:54:13 <samccann> #endmeeting