15:01:08 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:08 <zodbot> Meeting started Tue Aug 23 15:01:08 2022 UTC.
15:01:08 <zodbot> This meeting is logged and archived in a public location.
15:01:08 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:08 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:08 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:18 <samccann> #chair ssbarnea Don Naro
15:01:18 <zodbot> Current chairs: Don Naro samccann ssbarnea
15:01:52 <samccann> Dule_Martins#0383: - I'll take a look later, thanks!
15:02:49 <samccann> @room Meeting time! Who is here to talk the docs?
15:03:11 <DonNaro[m]> hello, hello. double booked as usual but I'm here.
15:03:13 <samccann> briantist: tremble felixfontein around to talk docs today?
15:04:08 <briantist> o/
15:04:20 <samccann> #chair briantist
15:04:20 <zodbot> Current chairs: Don Naro briantist samccann ssbarnea
15:04:35 <briantist> triple booked 😩 so I might just.. sort of drift away, sorry in advance
15:05:14 <samccann> no worries, thanks for drifting in for a bit!
15:05:25 <samccann> #topic Docs Updates
15:05:38 <samccann> #info archiving 2.3 docs hopefully this week. They will be available from docs.ansible.com/archive.
15:06:35 <samccann> As a reminder, once it's up, we'll add redirects from the old pages (docs.ansible.com/ansible/2.3/ to /latest/.  That should remove all the google top hits over time that are going to this ancient docset, but still leave them available elsewhere for people still needing 2.3
15:06:36 <acozine> o/
15:06:43 <samccann> #chair acozine
15:06:43 <zodbot> Current chairs: Don Naro acozine briantist samccann ssbarnea
15:06:45 <samccann> welcome welcome
15:08:02 <samccann> #info Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
15:08:14 <samccann> #info Help on issues always welcome :-)
15:08:28 <felixfontein> o/
15:08:51 <acozine> #chair felixfontein
15:08:51 <zodbot> Current chairs: Don Naro acozine briantist felixfontein samccann ssbarnea
15:08:54 <samccann> #chair felixfontein
15:08:54 <zodbot> Current chairs: Don Naro acozine briantist felixfontein samccann ssbarnea
15:09:00 <acozine> heh
15:09:14 <samccann> haha doublechaired!  I think you just became our first official sofa!
15:09:45 <briantist> haha
15:09:46 <samccann> Anyway the new project board can be sorted by size or priority etc etc. So... at least we have some sense of what we should do next ;-)
15:10:06 <samccann> Tho I still have only 1/2  the existing issues on there. I hope to get the rest triaged this week
15:10:51 <acozine> line 'em up, knock 'em down, eh?
15:11:15 <samccann> lol yep
15:11:23 <samccann> #info User guide is being split into multiple guides. See https://docs.ansible.com/ansible/devel/index.html for current status. More to come.
15:11:58 <samccann> Don Naro split out a couple more guides last week, and I think a few more on the way.
15:12:11 <acozine> that sounds great!
15:12:17 <DonNaro[m]> hopefully the last of them soon!
15:12:47 <samccann> coolness! once they are all out there, we can ask for feedback etc. Tho I think we've publicized this quite a bit.
15:12:59 <samccann> But a final bullhorn toot might be good
15:13:05 <DonNaro[m]> for sure
15:13:41 <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:14:29 <samccann> #topic doc tools updates
15:14:32 <samccann> #info docs warnings down from 1.1K to 174 thanks to antsibull-docs update!
15:14:54 <samccann> that ^^ is such a big relief! Thanks for that felixfontein
15:15:43 <samccann> #info this will not be part of the docs requirements until early September, so you'll have to manually update `antsibull-docs` >= 1.3 to get this locally
15:15:59 <samccann> That brings up another topic.  We should have a target 'freeze' date in mind for `antsibull-docs` etc.
15:16:41 <samccann> At least in the sense of we'll want to have a version released before core freeze so we can update the requirements and have time for the core folks to update the CI containers etc, all before the 2.14 branch is pulled
15:17:54 <samccann> branch pull/core freeze is Sept 19th
15:18:15 <acozine> what are you thinking? a week before?
15:18:39 <samccann> Yes. Monday Sept 12th.
15:18:48 <samccann> felixfontein: what do you think?
15:19:13 <samccann> of course changes can still come later, but they won't be part of the 2.14/Ansible 7 release
15:20:07 <felixfontein> thanks for the double chair ;)
15:21:00 <felixfontein> I'm happy with that, assuming that core gets the PRs this will depend on merged in time so we have at least some days for adjusting antsibull-docs *before* that
15:21:23 <samccann> can you elaborate?
15:21:45 <samccann> there's the PR to change the requirements in CI
15:21:55 <samccann> Then there's probably CI container work from core...
15:21:59 <felixfontein> well, core did not want the last antsibull-docs update PR merged because they were still working on the filter/test docs feature
15:22:06 <felixfontein> there has still not been an update on that
15:22:26 <felixfontein> if that refactoring is only merged directly before freeze, there's no time to adjust antsibull-docs to potential changes caused by that
15:22:41 <felixfontein> (something very similar happened directly before the previous freeze IIRC)
15:22:44 <samccann> okay so I thought so long as the sidecar docs feature doesn't merge for 2.14, we are okay with updating antsibull-docs.
15:22:58 <samccann> ah ok so let me see if I understand this
15:23:23 <samccann> if sidecar docs merges, we need 'some time' to fix potential antsibull-doc changes
15:23:48 <samccann> if sidecar docs doesn't merge, we are okay with antsibull-docs 1.3 or greater? or we still have to remove something?
15:24:14 <felixfontein> the feature has already been merged, but apparently they want to change something
15:24:42 <samccann> ah ok. So as it is TODAY, anstibull-docs works?
15:24:53 <samccann> but if they change something, we may need to change something?
15:24:54 <felixfontein> yes, it works totally fine from my point of view...
15:25:12 <felixfontein> it would work better if all tests/filters are documented, but that's another thing that I have no influence on
15:25:34 <felixfontein> yes, if they change something, we might need to change something... but we only know once we know what they are changing
15:25:50 <samccann> ok after the meeting, I'll ping matt and brian to open the discussion a bit here to see what their thinking is on the timeframe etc
15:26:11 <samccann> the gist of it is, if there's a change, we need X days to adapt to the change before we freeze our requirements.
15:26:37 <samccann> which means potential backports if the core change happens say on Sept 19th :-)
15:27:33 <samccann> do you foresee any scenario were we'd end up having to STAY on `antsibull-docs` 1.0.0?
15:28:48 <felixfontein> is feature freeze on sept 19th? then yes ;)
15:29:04 <felixfontein> I really hope we not have to stay with 1.0.0, that would be a real huge bummer
15:29:29 <samccann> well I'm asking are there technical gotchas that might end up with that happening?
15:29:55 <samccann> like sidecar docs goes upside down and the level of change needed to compensate in ansible-docs is too big to do in a few days for example
15:30:14 <samccann> I just remember that went in say version 1.1 and we are at 1.3 now and looking at 1.4 at least before freeze, right?
15:30:21 <felixfontein> I don't think so... except if core says "antsibull-core must not load filter or test plugin docs even though ansible-doc supports them", then we might have a problem
15:30:43 <samccann> ok cool thanks
15:31:30 <samccann> @action samccann to open discussion on when we can get CI container updates for 2.14 (esp if it has to happen after branch pull due to late changes in sidecar docs-related feature
15:31:38 <samccann> dagnammit!
15:31:49 <samccann> #action samccann to open discussion on when we can get CI container updates for 2.14 (esp if it has to happen after branch pull due to late changes in sidecar docs-related feature
15:31:52 <samccann> there, that's better
15:32:06 <samccann> #info Switching boolean yes/no vs true/false based on https://github.com/ansible-community/community-topics/issues/116.
15:32:24 <samccann> Other than ^^ also depends on antsibull-docs 1.3 or greater, what else is our status here?
15:32:48 <felixfontein> I would say "it just works" ;)
15:33:01 <samccann> I seem to recall brian had a quick PR after last week's discussion, but I don't remember what  the PR was and if it was merged (for related core changes for ansible-docs output to use true/false)
15:33:05 <felixfontein> no idea what's ansible-doc's status is. there is that WIP PR by brian, but I don't think it's near completion
15:33:15 <samccann> ah ok thanks
15:33:43 <felixfontein> https://github.com/ansible/ansible/pull/78561 - right now there are syntax errors that need to be fixed
15:33:50 <samccann> So for the things 'under our control) aka the html docs - what do we do about all the examples in the module docstrings? Those I think would not be 'fixed' by the antsibull-change
15:34:12 <samccann> #action sammcann to nag about https://github.com/ansible/ansible/pull/78561 status
15:34:12 <felixfontein> no, these have to be changed manually in all the collections involved
15:34:33 * samccann possibly shouldn't call action items nagging in meeting minutes but what the heck :-)
15:34:58 <felixfontein> :D
15:35:18 <samccann> #info the remainder of boolean work involves the WIP PR https://github.com/ansible/ansible/pull/78561 for core, and manually changing collection examples in each collection
15:35:49 <samccann> #action samccann to open an issue 'somewhere' to track all the collections that need this change
15:36:10 <samccann> once we have a list, we can open issues on all those collections... cuz that just sounds like a party!
15:36:18 <felixfontein> some collections might not want to change (for $random reason), but we can still ask all of them :)
15:36:46 <felixfontein> I *think* I already adjusted community.docker, but I have to check...
15:36:59 <samccann> that's an interesting point. Since the steering committee said 'thou shalt use true/false' does that not make it mandatory for collection owners to change?
15:37:28 <samccann> as it does this become a MUST or a SHOULD for collections inside the package?
15:37:32 <samccann> ssbarnea: ^^
15:38:47 <felixfontein> I think it will only be a SHOULD
15:39:02 <felixfontein> I don't think MUST is a good idea - at least yet. maybe in the far future :)
15:39:09 <samccann> ok for my own edification, I'll go get that clarified.
15:39:32 <felixfontein> I'd wish that I can make the true/false changes *together* with semantic markup, since then I'd only hvae to go through all docs *once*
15:39:46 <felixfontein> but I guess we don't have that luxury :)
15:39:50 <samccann> Well that's the question - MUST means say new collections MUST use true/false and would fail the inclusion criteria if they didn't
15:39:56 <samccann> sadly
15:40:14 <samccann> and MUST would mean existing collections whould have to change by.. some future Ansible release
15:40:45 <samccann> but historically, we haven't excluded any collection because of docs problems (other  than no docs at all) so maybe it really is SHOULD
15:40:56 <felixfontein> from my POV, as long as not even the latest docsite and ansible-doc use 'true' and 'false', we cannot really require collections to change all their docs
15:41:28 <samccann> true
15:41:36 <felixfontein> well, I would veto a collection which has horrible docs ;) but that didn't happen so far (or maybe only for ones grandfathered in...)
15:41:46 <briantist> the inclusion criteria and checklist do have docs requirements there, that are probably more strict than any of the grandfathered ones, yeah
15:41:49 <samccann> and it's complicated by Automation Hub, which still has yes/no for ..who knows how long into the future
15:42:11 <briantist> on the review I just did, the bulk of issues I found were in docs, thankfully, I marked some as should fix, and many as must fix
15:42:28 <felixfontein> I wish someone could tell me which part of AH is doing the docs formatting...
15:42:41 <samccann> #action samccann to followup with whether boolean examples MUST or SHOULD be true/false in collection inclusion criteria
15:45:54 <samccann> #topic Open Floow
15:46:17 <samccann> We have a few minutes left. Here's the time you can bring up anything docs-related for discussion
15:47:13 <felixfontein> is there a feature someone is looking for in antsibull-docs?
15:47:21 <samccann> ...including whether the A in the Ansible ascii cow should be above the udders or closer to the rump rawtaz  :-)
15:47:31 <felixfontein> and: are there news on semantic markup?
15:47:47 <felixfontein> lol, that's an interesting question
15:47:58 <samccann> semantic markup - no news but I did just ping internally  as a reminder.
15:48:08 <felixfontein> I asked my cats, they just said "feed us, ignore that ansible stuff"
15:48:27 <samccann> features on ansible-docs - other  than the issues opened, I haven't heard anything else
15:48:32 <samccann> LOL!  Cats know their biz
15:49:41 <felixfontein> https://github.com/ansible-community/antsibull-docs/issues/ currently has zero open issues ;)
15:50:03 <samccann> back to cow udders - I think we may be stuck on that one. I know there are T-shirts with that symbol on them... tho frankly I'd have to pull one out of a drawer to see if it exactly matches our 404 page or not :-)
15:50:26 <samccann> anyone have anything else to bring up before we end the meeting?
15:50:40 <acozine> heh
15:50:50 <acozine> I'm working on a PR to the inventory intro page
15:51:00 <samccann> woot thanks!!
15:51:00 <acozine> based on my problem yesterday
15:51:48 <samccann> ok seems quiet so gonna end this
15:52:14 <felixfontein> :+1:
15:52:43 <samccann> #endmeeting