15:00:32 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:00:32 <zodbot> Meeting started Tue Apr 26 15:00:32 2022 UTC.
15:00:32 <zodbot> This meeting is logged and archived in a public location.
15:00:32 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:32 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:32 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:00:44 <samccann> #topic opening chatter
15:00:50 <samccann> Who's around to talk the docs today?
15:01:01 <samccann> @room meeting time!
15:01:10 <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:01:34 <samccann> briantist: andersson007_  you folks around to chat docs?
15:02:19 <felixfontein> sorry, I'm mostly afk today :/
15:02:30 <samccann> ok thanks for letting me know
15:02:59 <samccann> If a dawgs meeting happens, and nobody's here but me, is it still a meeting?  Time will tell ;-)
15:03:23 <gwmngilfen-work> i'm here but I don't have any agenda 😉
15:03:45 <samccann> ahaha
15:03:51 <samccann> #chair Gwmngilfen
15:03:51 <zodbot> Current chairs: Gwmngilfen samccann
15:04:03 <samccann> at least I'm not talking to myself now!
15:04:15 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1102821830
15:04:50 <samccann> #topic Documentation Updates
15:04:53 <samccann> #info distro install page published - https://docs.ansible.com/ansible/devel/installation_guide/installation_distros.html
15:05:03 <briantist> o/
15:05:18 <samccann> I'll be doing backports to 2.13 later this week so that will be the 'new' latest when 2.13 releases
15:05:23 <briantist> sorry, very overbooked with meetings 😩
15:05:23 <samccann> Welcome briantist !
15:05:31 <samccann> #chair briantist
15:05:31 <zodbot> Current chairs: Gwmngilfen briantist samccann
15:05:45 <samccann> Well I had one specific question for you so I can pop that up now
15:05:52 <samccann> #info - Is it time to put some docs around how to test collection documentation? see https://hackmd.io/w6JSHW_XRzi9cBZtoN4snA for very rough draft.
15:06:28 <samccann> aka - we had two folks wanting to update stuff on ansible/ansible that needed to move to collections. Both were quite willing to do it, but how to do it was lacking in details, as well as how to test it locally
15:06:56 <samccann> I know this is an interim phase, but wondering if we need to add it to docs.ansible.com? or maybe add a pointer to the hackmd file so it
15:07:05 <samccann> is easier to update until it's finalized etc?
15:07:24 <briantist> it has been time to have docs for that, I am just buried, there's nothing blocking it except taking the time really..
15:07:55 <briantist> there's two different things here though: building docs locally, and using the github-docs-build actions to do automated build/publish in a collection
15:08:23 <briantist> your notes are basically perfect for building locally, I think
15:08:27 <samccann> ah good to know. So I have the building/testing locally okay. but I jus point to your github actions on the rest
15:09:08 <briantist> yeah exactly.. it's just that I don't have any good "getting started" docs on the github-docs-build repo (yet!)
15:10:11 <samccann> okay well it's worth a pointer anyway because some folks will just be able to figure it out on their own.
15:10:33 <samccann> The next question - should  this hackmd be in docs.ansible.com, or just a pointer to it?
15:11:21 <briantist> yup! it's pretty easy for the simple cases, and  can point at a few repos that have implemented it
15:12:06 <briantist> the hackmd? I suppose should be somewhere on docs.ansible.com . Each collection could also put up their own, like I have this one:
15:12:35 <briantist> https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/docsite/contributor_guide.html#collection-docsite
15:13:24 <briantist> (but that's because I took extra steps to commit the output of `antsibull-docs sphinx-init`, so general instructions in a central place are useful)
15:13:58 <samccann> ok cool
15:14:31 <samccann> #action samccann to move https://hackmd.io/w6JSHW_XRzi9cBZtoN4snA  into official docs and maybe point to https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/docsite/contributor_guide.html#collection-docsite as an example of how a collection owner can document this.
15:14:34 <samccann> thanks!
15:14:49 <samccann> #info - Documenting wheels - do we need to mention this in the basic pip install, or is it noise for most users?  Do we put pip download in a supplemental install page to say that's how you get everything?
15:15:06 <samccann> So I know the ansible package install is 'wheels' now, but I don't know if the end user cares?
15:15:17 <samccann> mostly thinking of users not developers
15:16:18 <briantist> my opinion is mostly no, the steps to install are the same whether wheels are used or not, so mentioning it might just be confusing, in the context of install steps
15:16:46 <samccann> ok cool. Just wanted to verify etc.
15:17:23 <briantist> it's not my area of expertise, so don't go by my feedback only :)
15:17:58 <samccann> haha i'll ping dmsimard later to see what he thinks. But your feedback matches my feelings as well.
15:18:13 <briantist> 👍
15:18:14 <samccann> aka don't add confusing details if 80% of the users won't care
15:18:28 <samccann> #topic docs builds
15:18:54 <samccann> So been having ahem.. some fun... trying to get stable-2.10 docs to build again.  mostly just so I can slap up an EOL banner in a month.
15:19:13 <samccann> Seems we never used pinning back then, so it won't build locally or w/ jenkins.
15:19:23 <briantist> oof :(
15:19:34 <samccann> indeed
15:19:35 <samccann> #info adding known_good to stable-2.10 in order to get the docs buildable again.
15:20:31 <samccann> so that's my solution - plop in a file that works. Also needed help updating the jenkins job because it defaults to python version of whatever.. erm.. VM it spins up (centos based I think)
15:20:43 <samccann> And 2.10 doesn't work on the docs builds anyway with python 3.8.
15:20:47 <samccann> so... fun times.
15:20:53 <samccann> I think it's all working now tho.
15:21:04 <samccann> But it brings up another tasty tidbit -
15:21:15 <samccann> #info replacing 'known_good' reqs file for docs with sanity-test reqs file so we don't need to keep them in sync - https://github.com/ansible/ansible/pull/77612#
15:21:57 <samccann> One of the problems we've had is keeping the docs requirement files in sync with CI (sanity tests).  So if finally dawned on me  - why don't we just USE the CI test requirements file instead?
15:22:11 <samccann> So that's what that PR is all about. Would love any feedback on whether this is a daft idea or not
15:22:47 <samccann> basically, anytime we updated our requirements, we hadto update sanity test as well, so it seemed logical to just skip having our own file
15:23:27 <samccann> we'll still keep the more open docs/docsite/requirements.txt which has minimal pinning. So anyone trying to build locally might have luck w/o getting into a ratrace of dependencies
15:24:40 <samccann> one final plug for the meeting minutes
15:24:48 <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:25:00 <samccann> #topic doctools
15:25:10 <samccann> #info splitting up the antsibull package - https://github.com/ansible-community/antsibull/issues/410
15:25:32 <samccann> felixfontein is mostly not around, but I think this one is close to done?
15:25:53 <briantist> I haven't been following it too closely so not certain
15:25:57 <felixfontein> I think it basically is. eventually we'll have to bump antsibull to 1.0.0, but there's no hurry ;)
15:26:39 <felixfontein> the only 'big' thing left is hunting down users of antsibull-lint and tell them to use antsibull-changelog or antsibull-docs instead
15:26:39 <samccann> Yeah I'd like us to coordinate with core when we need to make changes, so we can potentially tie it into any other test container changes they have planned.
15:26:58 <samccann> sounds like a bullhorn item ^^ ;-)
15:27:02 <felixfontein> since antsibull itself is no longer a dependency of anything in core, that shouldn't be needed :)
15:28:12 <samccann> Well I asked matt in that PR and his answer suggests we will still have to coordinate on anything that shows up in sanity.. and that includes anstibull-doc at least
15:28:46 <felixfontein> yes, but only antsibull-docs, not the antsibull package :)
15:29:33 <samccann> true
15:30:32 <samccann> okay I'm out of  things on my agenda so gonna...
15:30:36 <samccann> #topic Open Floor
15:30:50 <samccann> This is the time to bring up anything docs related. Got a fav PR or issue? time to mention it
15:32:32 * samccann sips tea
15:33:03 <samccann> I'll give one a try - Any ideas how we get more interest/discussion/contributions going on the docs?
15:33:29 <samccann> This meeting has gotten less and less attention over the past few months. I know I've used the community-topics a bit more, so maybe that's part of it?
15:34:29 <samccann> Gwmngilfen: is there a way to see trends on our actual docs contributions?  Maybe I'm just feeling lonely here but we are still getting the same (or maybe more?) actual PRs submitted for docs over  time?
15:34:44 <briantist> I wish I knew.. I have a hard time even getting feedback on my own collection, I don't really know how to get attention from my own community
15:35:05 <gwmngilfen-work> so because it's not a dedicated repo, it's kinda tricky
15:35:32 <gwmngilfen-work> you either have to trust the labels (questionable) or pull out what paths a PR touches
15:36:14 <gwmngilfen-work> can be done, but I don't have it to hand right now
15:36:20 <samccann> Well our ansible/ansible PRs always have the `docs` or `docs_only` labels
15:36:28 <samccann> the bot assigns them
15:36:34 <gwmngilfen-work> that i might be able to do quickly then 🙂
15:36:40 <samccann> heh cool
15:37:16 <samccann> Meanwhile, maybe we all need a master class in growing communities? Possibly a topic for the next contributor summit? Seems like with 100 or so collection owners, it might be a useful topic
15:38:18 <samccann> Gwmngilfen: is there any way to see if people are reading meeting minutes? I know the agenda and minutes are all one big long github issue, but I don't see anything obvious that says # of followers on that issue for example
15:38:41 <gwmngilfen-work> not really, github won't give you that
15:38:50 <gwmngilfen-work> afaik
15:38:59 <samccann> ok thanks
15:39:11 <samccann> Anyone else have an open floor topic or ideas to chat about?
15:40:19 <samccann> ok seems a bit quiet so gonna call it a day
15:40:25 <samccann> #endmeeting