15:01:15 <acozine> #startmeeting Docs Working Group aka DaWGs
15:01:15 <zodbot> Meeting started Tue Apr  6 15:01:15 2021 UTC.
15:01:15 <zodbot> This meeting is logged and archived in a public location.
15:01:15 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:15 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:15 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:01:16 <abadger1999> Bom dia!
15:01:20 <felixfontein> \o/
15:01:24 <acozine> #topic opening chatter
15:01:33 <acozine> Hi abadger1999 and felixfontein!
15:01:34 * samccann waves
15:01:45 <acozine> #chair abadger1999 felixfontein lmodemal samccann
15:01:45 <zodbot> Current chairs: abadger1999 acozine felixfontein lmodemal samccann
15:01:52 <acozine> who else is around?
15:01:54 <tadeboro> o/
15:02:08 <acozine> hi tadeboro!
15:02:14 <acozine> #chair tadeboro
15:02:14 <zodbot> Current chairs: abadger1999 acozine felixfontein lmodemal samccann tadeboro
15:03:17 <acozine> andersson007_: dericcrago dmsimard aminvakil baptistemm briantist cyberpear kindlehl madonius mrproper tremble tributarian you folks chatting docs today?
15:03:50 * tremble will lurk
15:03:59 <acozine> if you are watching this chat and thinking, "my name is not on that list, can I join?" . . . the answer is YES!
15:04:08 <acozine> tremble: do you want to be furniture?
15:04:10 <tremble> nah
15:05:03 <acozine> if you are watching this chat and thinking, "why is she talking about furniture, I thought this was a documentation channel?" - "being furniture"  is a joke - it means being a "chair" of the meeting
15:05:26 <acozine> and anyone can become furniture, just wave like this: `o/` or say hi
15:06:29 <acozine> today's official agenda begins with: https://github.com/ansible/community/issues/579#issuecomment-810396330
15:07:26 <acozine> we have a lot of "follow up" items
15:08:26 <acozine> but I'd like to shake things up a little
15:08:44 <acozine> #topic PR and issue counts keep growing
15:09:16 <acozine> even in the main ansible/ansible repo, documentation PR numbers keep going up
15:09:24 <acozine> right now we've got 95 open docs PRs: https://github.com/ansible/ansible/pulls?q=is%3Apr+is%3Aopen+label%3Adocs
15:10:26 <acozine> can we do a quarterly or monthly triage session or hackathon or something to get the numbers back down?
15:10:41 <samccann> that sounds like a great idea
15:10:50 <acozine> do the collections repos have many (any) docs PRs as well?
15:12:07 <acozine> tadeboro: do you get community contributions to the collections you maintain?
15:12:51 <acozine> gundalow: gwmngilfen do either of you have a sense of how fast PRs are coming in for the community collections?
15:12:59 <tremble> The AWS collections get a few, mostly things like bugs in the examples
15:13:01 <abadger1999> andersson007_, dericcrago, dmsimard ^ question about numbers of docs PRs in the collection repos.
15:13:07 <felixfontein> there are some docs contributions in community collections, not too many though
15:13:21 <acozine> tremble: good to know, are they mostly merged quickly?
15:13:23 <felixfontein> (at least in the ones I look at)
15:13:37 <tadeboro> I must admit that I do look at those PRs from time to time. But because quite a lot of them change documents that should be moved to collections (scenario guides mostly), I often lose interest.
15:13:38 <tremble> What keeps catching folks out is that they'll update the .md files instead of the modules
15:13:54 <gundalow> acozine: there is a steady flow of PRs for community collections
15:14:11 <acozine> gundalow: steady flow in and steady merge rate as well?
15:14:24 <tremble> acozine, Mostly depends how busy folks are.  I try to at least review them quickly, they're generally some of the easier ones to review
15:14:32 <gundalow> acozine: well merge rate can always improve
15:14:56 <acozine> gundalow: true, but we're mostly keeping up?
15:14:57 <felixfontein> tremble: same for the ones I see
15:14:59 <tadeboro> As for the documentation contributions, I think we did not get any (because our docs rock ;)). But we did get notified when our docs site went down, so I have a hope people do use them.
15:14:59 <gundalow> +1 to PR days
15:15:10 <gundalow> acozine: nop, community PR backlog is increasing slowly
15:15:19 <felixfontein> sometimes it is a bit complicated to help the authors to improve the formatting of what they suggest, but usually it's pretty quick
15:15:43 <acozine> tadeboro: that sounds awesome, the best of both worlds
15:16:47 <acozine> gundalow: when is the next Big PR Day? should we do a Mini PR Day for Docs? or wait and join forces with the larger community? or . . .?
15:17:12 <felixfontein> PR day for docs sounds good as well
15:17:46 <acozine> it might attract folks who are intimidated by code PRs . . .
15:18:19 <acozine> or just folks who don't code, do use Ansible
15:18:26 <felixfontein> yep, it's much easier to participate
15:18:49 <lmodemal> I like docs PR day as well
15:20:14 <acozine> proposal: Mini Docs PR Day next Tuesday, starting 1 hour earlier than the DaWGs meeting and lasting 4 hours
15:20:34 <acozine> too soon? too long? too short? worth a try?
15:20:42 <tadeboro> I tend to look at such things late in the evening when the rest of the house goes to sleep, but having a mini-PR-review-marathon does sound good.
15:21:02 <acozine> tadeboro: so later in the day would be better for you?
15:21:07 <samccann> erm... aren't we in mandatory training on that tuesday acozine ?
15:21:11 <acozine> oh
15:21:13 <acozine> erm
15:21:18 * acozine checks calendar
15:21:30 <acozine> good thing samccann keeps an eye on these things
15:21:52 <gundalow> acozine: We can do a dedicated Docs one
15:21:58 <samccann> heh only because I already had to move something out of those training windows yesterday
15:22:44 <acozine> well, in general is "docs PR day on the same day as the usual DaWGs meeting" a good thing for folks?
15:22:56 <acozine> or should we do it on a different day?
15:23:19 <felixfontein> for me it depends on the concrete date, so hard to say in general :)
15:23:20 <tadeboro> An extended DaWGs meeting works for me.
15:23:58 <acozine> okay, revised proposal: April 20 (Tuesday) starting 1 hour before the usual DaWGs and lasting 4 hours?
15:24:15 <acozine> gundalow: would that work for you?
15:24:20 <gundalow> acozine: I think this is a general case of
15:24:20 <gundalow> something > nothing
15:24:20 <gundalow> so for me picking a date is good
15:24:45 <tadeboro> I have no idea how things will stand next week (homeschooling is fun), so any date is in the "I will do my best" category ;)
15:24:51 <acozine> heh
15:25:02 <acozine> yep, life is particularly unpredictable right now
15:25:07 <acozine> let's give it a try
15:25:32 <acozine> we can post a draft agenda for the 20th today, along with next week's
15:26:09 <acozine> #agreed we will try a Docs PR Half-Day on April 20th, starting one hour before the usual DaWGs meeting, lasting 4 hours
15:27:00 <acozine> #topic updates on long-running topics
15:27:24 <acozine> our current list of in-progress items is:
15:28:02 <acozine> - Ansible package `devel` docs should use latest releases of package-included collections from Galaxy
15:28:33 <acozine> - template for putting `.rst` files into the collection `/docs/` folder in a subfolder
15:28:53 <acozine> - semantic markup for module documentation
15:29:03 <acozine> - docs for filter/test plugins
15:29:30 <acozine> - what to do about HTTP redirects for old module-docs URLs
15:29:38 <acozine> (as time goes by)
15:30:09 <acozine> and finally:
15:30:47 <acozine> - bcoca's proposal from 2017 for a new field in module docs https://github.com/ansible/proposals/issues/68
15:31:17 <acozine> abadger1999:  any updates on the devel docs work?
15:31:52 <bcoca> acozine: have PR already
15:31:54 <samccann> I wanna say we were waiting on a volunteer to do the coding side of the /docs folder work, but never heard back from them?  abadger1999 sound at all familiar?
15:31:58 <abadger1999> I didn't have a chance to work on it with Friday off last week.  This week I have some personal stuff that will likely take me out of work for part of the week.
15:32:05 <bcoca> https://github.com/ansible/ansible/pull/73707
15:32:11 <abadger1999> Yeah, someone did volunteer.
15:32:14 <acozine> abadger1999: hooray for time off in spring!
15:32:26 <abadger1999> But we haven't seen them since two meetings ago.
15:32:52 <acozine> yeah, I think that person is unlikely to follow through right now
15:32:59 <acozine> unfortunately
15:33:03 <samccann> yeah so seems like we need another volunteer ;-)
15:33:06 <acozine> heh
15:33:48 * felixfontein still has to take a look at bcoca's PR
15:34:59 <acozine> bcoca: is there any way we could make those attributes links to the rst/html pages that document the behaviors?
15:35:55 <acozine> as in, `become: support: yes` would link to https://docs.ansible.com/ansible/latest/user_guide/become.html
15:36:44 <bcoca> acozine: ansible-doc outputs them in the json s o its easy to add ontop
15:36:49 <acozine> awesome
15:37:07 <acozine> what is the difference between `support: yes` and `support: full`?
15:37:25 <bcoca> partial support is possible in some cases, feedback welcome
15:37:36 <acozine> ah
15:38:12 <acozine> maybe only 3 possible values: `no`, `partial`, and `full`?
15:38:16 <samccann> i'd suggest `support: partial` yeah
15:38:49 <acozine> this is a nice feature, bcoca!
15:39:18 <bcoca> been on my list for long time .. filters/test docs next
15:40:27 <acozine> what was the discussion around adding an `orphaned` field? https://github.com/ansible/proposals/issues/68#issuecomment-630977395
15:41:51 <bcoca> its possible, but since we moved to collections i saw that as not as needed since now that would be a collection level 'feature'
15:42:07 <acozine> I don't understand what the use case for it was
15:42:10 <bcoca> made more sense when all plugins were in core and 'metadata' was not that flexible
15:42:20 <bcoca> to point to 'unmaintained' plugins
15:42:25 <acozine> ah, okay
15:42:47 <acozine> so something like deprecated, but less . . . um . . . definitive?
15:43:22 <abadger1999> orphaned metadata makes just as much sense in the collection world as pre collection world.  But I am on the fence as to whether it belongs in a documentation field
15:44:13 <abadger1999> I lean slightly towards it being better kept out-of-band but I haven't had anyone make a case for it in the documentation strings to me.
15:44:20 <samccann> under what conditions would a maintained collection have an unmaintained plugin and keep it?
15:44:45 <felixfontein> samccann: becaues nobody wants to delete code that currently still works :)
15:44:47 <samccann> or maybe I should ask specifically - would something big like c.g keep an unmaintained plugin around?
15:44:51 <samccann> heh ok
15:45:13 <bcoca> only c.g .. i would not expect any other collection to do so
15:45:18 <samccann> so unmaintained means nobody is fixing bugs but it's still possibly useful
15:45:34 <acozine> "it works, or at least we think it works, but nobody has touched in in 3 years . . . here be possible dragons?"
15:45:37 <bcoca> that describes 80% of plugins that were in core in 2.9
15:46:11 <acozine> I vote for keeping that out of the docs
15:46:33 <bcoca> system is easy to extend, so dont need to commit to it now
15:47:03 <acozine> unless/until we have some objective criteria, like "no code changes in 3 years means a plugin is orphaned" and we can automate the process of orphaning/de-orphaning
15:47:05 <samccann> why not in docs? Seems useful to see 'unmaintained' status
15:47:15 <bcoca> the current list are 'known examples' that i'm tired on repeating in diff modules or expliaining to users when hit
15:47:45 <acozine> it feels like "orphaning" could get controversial pretty quickly
15:47:46 <abadger1999> samccann: there's likely to always be umbrella collections around.  If we removed community.general and community.network other  community people would create different versions of those.
15:48:21 <samccann> yeah makes sense. Just not following the logic of why we wouldn't want this status in the docs
15:48:33 <abadger1999> It fills a niche where people can share release engineering duties to make releases of software that they care about.
15:49:35 <acozine> I'd be okay with adding the status to docs if we have a clear policy and it's not just "this feels kinda old to me"
15:49:45 <samccann> agreed
15:50:28 <acozine> and we don't have it now
15:50:45 <acozine> although we could, I guess
15:50:49 <abadger1999> This is off the cuff, From a logistical standpoint, I think it makes more sense to maintain such a list separate from the modules themselves.
15:51:05 <acozine> maybe something for the community WG to discuss . . .
15:51:18 <abadger1999> Because if a module isn't being updated (because it is unmaintained) it may be hard to get the documentation strings inside of the modules updated as well.
15:51:50 <felixfontein> for me, having the orphaned information in the module/plugin docs would be helpful so it's easier for people to notice that something is not maintained
15:51:55 <abadger1999> depending on the activity of the containing collection
15:52:13 <felixfontein> looking in BOTMETA (the best separate place?) is not anything regular people will do
15:52:20 <acozine> yeah, I definitely see how it could be useful
15:52:35 <abadger1999> <nod> I do think being able to show that list is helpful.  I just am hesitant that inside of the DOCUMENTATION string is the best place.
15:53:07 <abadger1999> Maybe we should make BOTMETA the canonical location (vague bells that we decided that once upon a time already?) and use that as a source of information for building the docs?
15:53:24 <acozine> that sounds like a good idea
15:53:27 <felixfontein> for collections such as c.g, DOCUMENTATION is as good as any other place
15:53:53 <bcoca> i thought we were removing botmeta soon
15:53:58 <abadger1999> A Con to using BOTMETA would be that gaaxy probably wouldn't use it.
15:54:10 <felixfontein> bcoca: that's for ansible/ansible; in c.g/c.n/... it will stay
15:55:16 <abadger1999> I guess a question would be... is this an ansible-project wide thing?  or is this a local-to-collection thing?
15:55:38 <felixfontein> right now, it's more local-to-collection
15:55:45 <felixfontein> very few collections have a BOTMETA, I think
15:56:49 <abadger1999> In the rpm world, we found that "Package Groups" had metadata inside of the individual packages but it was really a project-wide piece of data (use case: "I want to show  the user in the installer groups of packages that they can install").
15:57:14 <acozine> maybe discuss in the community WG first? then when we know what the goals and criteria are, we can discuss implementation in the DaWGs?
15:57:26 <samccann> sounds good
15:57:29 <abadger1999> here, I look at it and say, as a project, we want to let people know that there is orphaned modules that need new maintainers.
15:57:43 <samccann> cybe-clock piping in late that we are 57 minutes into the meeting
15:57:52 <acozine> heh
15:57:55 <abadger1999> but perhaps that's not the model we want (or perhaps here it's not the only model we want)
15:58:02 <samccann> and didn't info a thing.. urf.
15:58:15 <samccann> #info /docs folder work needs a volunteer to do the coding
15:58:21 <acozine> I put at least one `agreed` in
15:58:39 <abadger1999> Did we agree on the format of the docs foleder?
15:58:56 <acozine> I think the docs folder issue needs updating
15:59:11 <acozine> IIRC we agreed to use a subfolder called `docs/docsite/rst`
15:59:13 <samccann> #info for https://github.com/ansible/ansible/pull/73707 - can we have partial instead of yes as a support option? And not doing orphan status until discussed/decided in the community meeting
15:59:22 <abadger1999> <nod>
15:59:25 <acozine> allow only .rst files in it
15:59:34 <acozine> and require an index.rst file
15:59:42 <acozine> everything else is up to the collection owner
15:59:56 <samccann> yeah we should write that up in a proposal somewhere so the person coding it knows what to expect etc
16:00:04 <abadger1999> Ah... did we decide how the index.rst gets merged into the collection's index?
16:00:13 <acozine> and we agreed to display a link to the index.html result on the collection index page
16:00:15 <felixfontein> I don't think we said anything on what this index.rst should be or contain
16:00:23 <felixfontein> abadger1999: i.e. no
16:00:30 <abadger1999> I think that was the last thing felix, samccann, acozine, and I were discussing.
16:00:36 <acozine> yeah, that sounds right
16:00:45 <samccann> index.rst is the ordered list of files/subfolders etc under docs/docsite/rst afaik
16:00:58 <samccann> but yeah, this all needs a writeup to be sure.
16:01:04 <abadger1999> felixfontein and I think that the feature should be able to merge more than one link into the collection page somehow.
16:01:21 <acozine> index.rst is the default page for the directory via http
16:01:38 <felixfontein> especially for filter/test docs, being able to add similar sections to the existing ones to the collection plugin index would be good
16:01:49 <acozine> so if you hit docs.a.c/. . . /collections/my_collection/ you hit that index page
16:02:18 <felixfontein> the index page for that directory is already auto-created
16:02:37 <samccann> yeah that would have to change then
16:02:46 <abadger1999> felixfontein: yeah, so something that has both headers and lists of page links to get merged into the collection page's hierarchy.
16:03:00 <samccann> my_collections/guides and my_collections/plugin_index for example
16:03:01 <felixfontein> samccann: I would really avoid to change that, that would result in utter chaos :)
16:03:34 <samccann> felixfontein then where do you think the collection level guides should appear?
16:03:48 <acozine> drat, i was supposed to update https://github.com/ansible-community/antsibull/issues/242
16:03:56 <felixfontein> (I meant the 'yeah that would have to change then')
16:04:22 <acozine> I'll try again this week
16:04:26 <felixfontein> samccann: they need to be listed in the auto-generated index.rst, but not by allowing (or forcing) the user to completely replace that page
16:04:58 <felixfontein> in my WIP PR I put all .rst files into a subdirectory (docsite/), to avoid them to accidentally overwrite auto-generated ones
16:05:03 <acozine> hm, so maybe the subfolder should be `docs/docsite/rst/guides`?
16:05:49 <acozine> so it would appear at docs.a.c/. . . /collections/my_coll/guides/index.html ?
16:06:27 <felixfontein> I'm for just putting everything in a subdirectory docsite/ (as my PR does), it's simple and shouldn't hurt
16:07:05 <felixfontein> if you put docs/docsite/rst/guides/ into guides/, where do you put files from docs/docsite/rst/?
16:07:36 <acozine> ahh, that's right, you created https://github.com/ansible-community/antsibull/pull/255
16:07:55 <samccann> ok so taking a brief step back. As a reader, I want to find all the docs for community.general in one location so i can bookmark it etc
16:08:31 <abadger1999> docs.a.c/. . . /collections/my_coll/index.html  should have headings and links to (potentially) multiple ad hoc guides on it.  I'm less concerned about the directory or url structure of that as it's less visible than getting the links onto the collection's toplevel index page.
16:09:03 <acozine> samccann: like this? https://ansible.fontein.de/collections/community/docker/
16:09:07 <samccann> ok felixfontein's WIP sample output has what I expected - a page that lists guides and plugins
16:09:25 <felixfontein> for example in https://ansible.fontein.de/collections/felixfontein/tools/ and https://ansible.fontein.de/collections/community/docker/ you can see all documents, but you will notice that the URLs for the 'custom' rst files are in a docsite/ subdirectory if you look closely
16:09:39 <tadeboro> We structured our collection home page like this: https://sensu.github.io/sensu-go-ansible/
16:10:09 <felixfontein> (having more freedom to modify the auto-generated index.rst is definitely nice, the index.yml file in the PR is somewhat limited)
16:10:40 <tadeboro> So in essence, what felixfontein proposed, but since we do not auto-generate it, we have a bit more freedom.
16:10:40 <acozine> I see two next steps here:
16:11:11 <felixfontein> tadeboro: I think I'd keep the plugin index and the header (title + collection version) fixed, so collection pages don't vary too much on docs.ansible.com
16:11:15 <samccann> cyb-clock - we are 1hr 10 min into the meeting, 12 minutes into this topic
16:11:34 <acozine> 1. put a scenario guide that's currently in ansible/ansible onto a collection branch and test publishing it with felixfontein's PR branch
16:11:43 <samccann> #info examples of the docs folder in action https://github.com/ansible-community/antsibull/pull/255
16:12:28 <acozine> 2. draft some community docs describing how to use this featuer
16:12:33 <acozine> oh, and . . .
16:12:56 <acozine> 3. get codecov passing on the PR
16:13:03 <samccann> heh
16:13:04 <acozine> (yep, fencepost error . . . )
16:13:09 <tadeboro> felixfontein: I agree. I just wanted to show that we placed roughly the same information into the index page.
16:13:10 <abadger1999> it's okay if codecov doesn't pass.
16:13:34 <acozine> abadger1999: merging PRs with failing tests??? that way madness lies, surely?
16:13:39 <samccann> heh
16:13:53 <samccann> do you want to info or action those next steps so we don't forget?
16:14:01 <abadger1999> (codecov tests failing means that there isn't testing for the PR but there isn't testing for most of the code right now... we've greed to start paying attention to codecov once we get more tests for existing code)
16:14:39 <acozine> #action acozine to create a PR that moves a Scenario Guide into a collection and uses felixfontein's PR https://github.com/ansible-community/antsibull/pull/255
16:15:43 <acozine> #info other next steps on collections /docs/ folder work: draft some community docs describing how to use the feature, make codecov happy if we can
16:15:49 <acozine> okay, we're at 15 minutes over
16:15:57 <acozine> quick open floor
16:16:02 <acozine> #topic open floor
16:16:18 <samccann> gonna ask a general question
16:16:29 <acozine> all comments, questions, ideas, suggestions welcome
16:16:41 <samccann> is there something in docs land we SHOULD be looking into/changing etc that we haven't discussed already here?  Something we are forgetting?
16:17:24 <acozine> hmmm, we could look again at the survey answers
16:17:29 <acozine> that might give us ideas
16:18:00 <acozine> and if anyone here knows of ways we could make the docs better, that would be great
16:18:21 <kindlehl> Is it helpful if I review docs PRs?
16:18:23 <samccann> #info we need to go back to docs survey results to see what might be next on our plates
16:19:11 <acozine> my instinct says to get breadcrumbs back up and running, get collection docs going, then try to clear the backlog of PRs and issues
16:19:25 <acozine> as a medium- to long-term plan
16:19:43 <acozine> kindlehl: yes, absolutely!
16:19:54 <samccann> yeah breadcrumbs are a must for the /docs thing anyway, going by felixfontein wip shows
16:20:16 <acozine> kindlehl: I've seen you put some comments on PRs already, that's great
16:21:00 <abadger1999> I think I can add a config option to turn breadcrumbs on and off fairly easily.  I'll look at making that a quick half-day project this week.
16:21:23 <acozine> abadger1999: that sounds great
16:21:56 <acozine> last call for open floor items
16:22:07 <samccann> #info next steps - get breadcrumbs back up and running, get collection docs going, then try to clear the backlog of PRs and issues
16:22:12 <felixfontein> abadger1999: that would be great! I already wanted to do that, but didn't got around...
16:22:14 <acozine> as a reminder, chat is welcome in the channel any time
16:22:33 <samccann> #info comments/reviews on PRs always welcome! It helps move them to completion and merging
16:22:42 <abadger1999> (Note, that it won't be a fix, just the ability to turn it on so you can test out any fix :-)
16:23:29 <acozine> yeah, for a fix we need changes in jenkins and/or greater efficiency in the code to match our resources on jenkins
16:23:40 <kindlehl> I'll try to review more docs PRs. I'm just hesitant because I'm not too familiar with the community and its standards.
16:24:01 <acozine> kindlehl: feel free to ask anything here
16:24:47 <acozine> we're generally kind and welcoming and we can help you learn community standards
16:25:00 <kindlehl> you're definitely kind. Very welcoming :)
16:25:10 <acozine> here's a link that might help: https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html
16:25:48 <acozine> all right, thanks abadger1999 acozine felixfontein lmodemal samccann tadeboro kindlehl bcoca tremble
16:25:53 <acozine> see you next week!
16:25:57 <acozine> #endmeeting