15:00:27 <acozine> #startmeeting Docs Working Group aka DaWGs
15:00:27 <zodbot> Meeting started Tue Jun  8 15:00:27 2021 UTC.
15:00:27 <zodbot> This meeting is logged and archived in a public location.
15:00:27 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:27 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:27 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:00:32 <acozine> #topic opening chatter
15:00:47 <cyberpear> o/
15:00:49 <felixfontein> o/
15:00:53 <lmodemal> DING DING DING!  DaWGs (documentation working group meeting) happening now https://github.com/ansible/community/issues/579
15:01:20 <acozine> heh, thanks lmodemal
15:01:30 <acozine> #chair cyberpear felixfontein lmodemal
15:01:30 <zodbot> Current chairs: acozine cyberpear felixfontein lmodemal
15:01:51 <lmodemal> o/
15:02:19 <acozine> who else is around? andersson007_ dericcrago dmsimard gundalow aminvakil baptistemm briantist tadeboro zbr you folks chatting docs today?
15:03:00 <felixfontein> a certain badger is probably asleep
15:03:08 <samccann> \o
15:03:18 <felixfontein> after being awake for way too long
15:03:22 <acozine> heh, I thought I saw him in the contrib summit, but I wouldn't blame him for heading right back to bed
15:03:32 <acozine> #chair samccann
15:03:32 <zodbot> Current chairs: acozine cyberpear felixfontein lmodemal samccann
15:03:49 <acozine> agenda begins with https://github.com/ansible/community/issues/579#issuecomment-852259347
15:04:10 <acozine> was he at the contrib summit through the whole thing???
15:05:17 <felixfontein> acozine: he actually was there from the beginning, though I guess he eventually fell asleep
15:05:39 <felixfontein> (sorry got a phone call :) )
15:05:43 <acozine> wow, he's two hours west of where i am, so it began at midnight his time . . .
15:06:01 <acozine> that is dedication!
15:06:15 <felixfontein> definitely!
15:06:52 <acozine> well, we will skip the agenda item about the devel docs this week, then
15:07:02 <felixfontein> :+1:
15:07:34 <acozine> #topic collection extra docs and Ansible 4.1 release . . .
15:07:52 <felixfontein> community.crypto, community.general and community.docker have docs/docsite folders, I'm looking forward to the 4.1.0 release and afterwards docsite rebuild :)
15:08:04 <acozine> yes, it's a very exciting moment
15:08:25 <samccann> #info community.crypto, community.general and community.docker have docs/docsite folders
15:09:04 <samccann> #info these should show up in their new place on docs.ansible.com/ansible after 4.1.0 releases (aka collection must be in the Ansible package before the docs will show up)
15:09:26 <acozine> and once we have those three up as examples, we can create the ticket to track moving the Scenario Guides out of ansible/ansible
15:09:37 <briantist> that is exciting.. I've been a bit out of the loop on it, though it's been in the back of my mind as I catch glimpses of the conversation
15:09:49 <briantist> any singular place I can read about it?
15:09:54 <acozine> #chair briantist
15:09:54 <zodbot> Current chairs: acozine briantist cyberpear felixfontein lmodemal samccann
15:10:18 <cyberpear> that's some exciting progress!
15:11:06 <acozine> briantist: see https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#docs-directory for initial documentation on how to use the feature, and https://github.com/ansible-community/antsibull/pull/255 for the code
15:11:27 <briantist> thank you!
15:11:38 <baptistemm> hello (lurking around only)
15:11:39 <felixfontein> and the repos of the above mentioned collections for examples
15:11:57 <acozine> also https://github.com/ansible/ansible/pull/74704 which we hope to merge soon
15:12:03 <acozine> hi baptistemm!
15:12:21 <felixfontein> actually the docs link above doesn't work yet, it's currently only on https://docs.ansible.com/ansible/devel/dev_guide/developing_collections_structure.html#docs-directory
15:12:36 <acozine> and https://github.com/ansible-collections/amazon.aws/pull/362 for the "incoming" content
15:12:46 <acozine> felixfontein: ah, oops - thanks for fixing that
15:12:54 <acozine> this is what happens when I get up too early ;-)
15:12:57 <briantist> heh thanks Felix, I was gonna say... that docs doc looks just like it always has ;)
15:13:02 <samccann> #info see https://docs.ansible.com/ansible/devel/dev_guide/developing_collections_structure.html#docs-directory for details on how to move scenario guides to a collection repo
15:13:11 <felixfontein> I just looked at it and tried to figure out where to find that info ;)
15:13:25 <samccann> #info and see https://github.com/ansible-collections/amazon.aws/pull/362 for an example of a moved scenario guide
15:14:49 <briantist> sorry if I missed this, but on what cadence will the collection docsite be updated?
15:14:59 <felixfontein> I guess the process will be easier for most other collections, since aws content is split up between two collections
15:15:10 <briantist> and how can we test it before publishing, to ensure links, formatting, etc. are correct?
15:15:16 <acozine> felixfontein: yeah, we're trying to figure that out
15:15:18 <felixfontein> devel is updated nightly I think, and latest after releases
15:15:31 <briantist> ok cool
15:15:33 <acozine> briantist: the collections docs are updated every three weeks when new versions come out
15:15:48 <felixfontein> briantist: you should always use `antsibull-lint collection-docs` for some first sanity checks
15:15:55 <acozine> devel is updated 4x/day but right now it only includes the `ansible.builtin` collection
15:16:15 <samccann> #info use `antsibull-lint collection-docs` for some first sanity checks
15:16:25 <acozine> ooh, that is an excellent question (about testing extra docs)
15:16:36 <acozine> something we definitely need to add to the documentation
15:16:46 <samccann> is there a way to test it fully?
15:16:46 <felixfontein> briantist: besides that, you can create a simple docsite like this: https://github.com/felixfontein/felix-ansible-docsite
15:17:05 <acozine> it should be possible to test locally as well
15:17:13 <felixfontein> (there's no need to upload the resulting HTML somewhere, you can just open it in your favorite browser)
15:17:55 <briantist> cool cool
15:18:05 <felixfontein> it's a small sphinx site which contains the content of some locally installed collections (https://github.com/felixfontein/felix-ansible-docsite/blob/main/Makefile#L11)
15:18:13 <samccann> we'll need a writup of how to do that... cuz i'm not following etc
15:19:06 <felixfontein> I want to clean it up a bit once all that ansible sphinx extension moving is done
15:19:53 <acozine> it replaces the `Makefile` we use in ansbile/ansible with a local equivalent so you can build the collection docs on their own
15:20:53 <acozine> so in that repo I think you'd do `make html_complete` and sphinx would build the set of included collections
15:21:19 <acozine> if I'm reading it correctly
15:21:21 <felixfontein> yes
15:21:32 <felixfontein> tidying it up includes adding a README ;)
15:21:36 <acozine> heh
15:21:51 <acozine> documentation for a documentation tool???
15:21:58 <felixfontein> yep ;)
15:22:00 <acozine> that way madness lies
15:22:23 <felixfontein> :)
15:22:23 <acozine> that's a cool and very useful example
15:24:04 <acozine> any other questions etc. about collection "extra docs"?
15:24:34 <acozine> I think this is really, finally the last bit of docs infrastructure for the collections move
15:24:55 <acozine> well, this and pulling in collections for `devel`
15:25:03 <felixfontein> I'm sure it's not the last bit, though probably the last most obvious bit ;)
15:25:11 <felixfontein> yep, that too
15:25:14 <acozine> still, when we look back at where we were a year ago . . . we've come a long way
15:25:33 <felixfontein> oh yes :)
15:26:03 <felixfontein> btw, what's the current status of https://github.com/ansible/ansible/pull/74318 ? I think someone mentioned during the summit, but I don't remember clearly anymore
15:26:12 <felixfontein> (sphinx_ansible_theme for ansible docsite)
15:26:29 <acozine> just needs a final test
15:26:44 <acozine> samccann: didn't you uncover something small yesterday that needed to be fixed?
15:26:54 <acozine> #topic Ansible Sphinx theme
15:27:23 <samccann> no. Just need your final review. I can restage it again if you want
15:27:30 <acozine> oh, okay
15:27:42 <acozine> I don't know what I'm thinking of . . . something that was missing
15:27:49 <acozine> in the nav? or . . . dang
15:27:58 <acozine> maybe that was days ago and sviat fixed it already
15:27:59 <samccann> i'll stage them both now maybe it'll jog our memories
15:28:07 <acozine> awesome
15:28:11 <samccann> last week the banners disappeared. He fixed that
15:28:22 <acozine> ah, that must be what I'm thinking of
15:29:11 <acozine> so it's ready to merge, unless we find something else to nitpick today
15:29:21 <samccann> yep
15:29:22 <samccann> I
15:29:41 <samccann> I will scan the PR again and approve it. Dunno if we need anything else (assuming the staging looks good)
15:29:50 <acozine> we could add something to the documentation about how to use the theme
15:30:06 <samccann> maybe something for the community docsite?
15:30:12 <acozine> yeah
15:30:31 <acozine> since this is mostly collections-focused
15:30:37 <samccann> #info  ansible-theme should be mergable soon. One final check on staging
15:30:41 <samccann> yep
15:30:49 <felixfontein> :+1:
15:31:38 <acozine> ooh, the rest of today's topics are ones we haven't gotten to in a long, long time
15:31:48 <samccann> progress!!!
15:32:10 <acozine> and we're at the 30-minute mark and have gotten through 2 topics
15:32:16 <felixfontein> I think I'll start creating some WIP PRs for the semantic markup
15:32:24 <felixfontein> so it finally will make some progress :)
15:32:25 <acozine> #topic semantic markup
15:32:36 <acozine> https://github.com/ansible/ansible/pull/73137
15:32:43 <acozine> er
15:32:53 <acozine> #info discussion from https://github.com/ansible/ansible/pull/73137
15:33:10 <acozine> do we not have a linkbot over here?
15:33:24 <felixfontein> looks like
15:33:26 <acozine> felixfontein: that sounds great
15:33:26 <felixfontein> dmsimard: ^
15:33:47 <felixfontein> did we have any consensus on https://github.com/ansible/ansible/pull/73137#issuecomment-784557342 ?
15:33:56 <acozine> it's always easier to discuss a problem or topic when there's a concrete solution being proposed
15:34:35 <felixfontein> true :) then I'll just pick something
15:35:07 <acozine> I like `P(name#type)`
15:35:29 <acozine> though the default for `type` should probably be `module`
15:35:42 <felixfontein> we could also just allow # in M(), thus keeping the current name and not introducing a new one
15:35:48 <acozine> true
15:36:02 <samccann> yeah what Felixfontein said
15:36:12 <acozine> but it goes against the grain to have a field `M` for module that can be set to a different type of plugin
15:36:20 <felixfontein> yep
15:36:24 <samccann> don't wannago through thousands of modules to change from M() to P()
15:36:43 <samccann> We can add `P(foo.type_)`
15:36:43 <felixfontein> we can keep M(...) as a shortcut for P(...#module)
15:36:47 <samccann> but keep M() yueah
15:37:02 * samccann being out-typed by felixfontein
15:37:06 <felixfontein> (and not have a default value for type in P())
15:37:11 <acozine> oooh, edgy
15:37:28 <acozine> will that complicate testing?
15:37:34 <felixfontein> makes P() easier to handle as well, since it always has a type, while M() never has one and is always module
15:37:42 <acozine> ah, that makes sense
15:38:11 <acozine> and I suppose if most references are still `M(.)` even for newly added modules, that's okay
15:38:25 <felixfontein> yes
15:38:38 <felixfontein> as long as I don't have to use R() for other plugin types :)
15:38:46 <acozine> my sense of The Proper Order Of Things wants everything to be `P(.)` but that's just the way my brain works
15:38:59 <acozine> it's not realistic or kind in the real world
15:39:21 <felixfontein> that's back to the old question "are modules plugins also to the user, or just internally?"
15:39:26 <acozine> yep
15:39:50 <acozine> and it just needs to be a little messy, I suspect
15:39:54 <samccann> #info considering leaving `M()` as is, and adding `P(name#type)` for all plugins e.g. `P(ansible.builtin.apt#module)` etc
15:40:49 <acozine> it'll be fun to document that
15:40:56 <felixfontein> it could be worse :)
15:41:19 <felixfontein> IMO optinally allowing #type is harder to document
15:41:38 <acozine> "You can also use `P(namespace.collection.module#module)` to refer to modules - because modules are actually a type of plugin!"
15:41:45 <acozine> nah, I meant that seriously
15:42:21 <acozine> I find it fun to describe technical stuff in a conversational tone
15:42:49 * acozine needs a `no_sarcasm` flag sometimes
15:43:42 <samccann> heh
15:43:51 <acozine> I'll update that PR to mention what we've discussed
15:45:31 <acozine> any other thoughts on semantic markup?
15:46:15 <acozine> it's quarter to the hour, maybe a quick open floor and we end a bit early today?
15:46:24 <samccann> cyb-clock-clone wakes up from a stupor to say - 45 minutes into the meeting
15:46:30 <acozine> heh
15:46:46 <acozine> #topic open floor
15:47:00 <samccann> gundalow brought up the topic of defining personas in the contrib. summit
15:47:32 <acozine> cool
15:47:37 <samccann> I think it makes sense to cover that with the community folks, but did we have any 'starter' ideas we wanted to put up in hackmd?
15:48:16 <acozine> the thing I struggle with is the dividing line between community, developers, and users
15:48:47 <acozine> maybe thinking about goals would help
15:49:11 <samccann> or my fav... user stories!!!
15:49:30 <acozine> "I want to give back" would be community and "I want to create a module" would be developer?
15:49:35 <gundalow> Was myself and Greg
15:49:37 <samccann> so what is a user looking for? what is a developer looking for etc
15:49:57 <samccann> acozine at the highest level yeah
15:50:07 <acozine> link to the hackMD?
15:50:11 <samccann> but there's also "I want to do a driveby pr to fix a nix'
15:50:29 <samccann> as in a contributor who just wants to do that one little thing and not have it all take forever
15:51:00 <acozine> yeah
15:51:12 <samccann> acozine is there a hackMD for this yet?
15:52:20 <acozine> oh, I misunderstood your comment before - I thought you said "do we have any 'starter' ideas to put in the hackMD" like one already existed
15:52:37 <samccann> oh haha .. s/the/a/g
15:53:59 <acozine> maybe we can add that for next week's agenda?
15:54:18 <acozine> and create a hackMD before then?
15:55:49 <samccann> well the idea was to create one to help the community folks use it in their meeting (tho not  this week since that's tomorrow)
15:56:04 <samccann> but I guess that's the higher question - which meeting should drive the conversation?
15:56:16 <acozine> https://hackmd.io/lAJfWYrlT3Gg1VXYGBoZtA
15:56:18 <samccann> I was thinkig community since they have more folks I think
15:56:39 <samccann> but I could go either way
15:57:17 <acozine> yeah, it will be a collaboration
15:58:24 <samccann> cyb-clock-clone sez we have 2 min left
15:58:26 <acozine> heh
15:58:31 <acozine> anything else for open floor?
15:58:49 <acozine> all comments, questions, suggestions, ideas, and criticisms welcome
15:58:54 <felixfontein> didn't we decide at some point how O(option=value) should look like?
15:59:06 <felixfontein> so far I only found discussions, though at least one I thought were we decided I cannot find
15:59:07 <samccann> #info we will be trying to create 'personas' and how each different ansible docs reader is looking for info in our docs. More to come
15:59:37 <acozine> felixfontein: I though so, but I'd have to dig around
15:59:45 <acozine> s/though/thought
16:00:50 <acozine> I'll have a dig through the records this afternoon
16:01:33 <acozine> reminder that agenda items can be added to https://github.com/ansible/community/issues/579 at any time
16:01:36 <acozine> by anyone
16:01:50 <acozine> and we meet in this channel at 15:00 UTC every Tuesday
16:02:06 <acozine> chat welcome at all times
16:02:08 <samccann> #info agenda items can be added to https://github.com/ansible/community/issues/579 at any time by anyone
16:03:02 <acozine> thanks baptistemm  briantist cyberpear felixfontein lmodemal samccann!
16:03:08 <acozine> #endmeeting