15:00:23 <ariordan> #startmeeting Documentation Working Group aka DaWGs
15:00:23 <zodbot> Meeting started Tue Oct 12 15:00:23 2021 UTC.
15:00:23 <zodbot> This meeting is logged and archived in a public location.
15:00:23 <zodbot> The chair is ariordan. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:00:23 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:23 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:00:40 <ariordan> Agenda https://github.com/ansible/community/issues/579#issuecomment-937868974
15:00:51 * acozine waves
15:00:52 <ariordan> Hi everyone!
15:01:04 <ariordan> Sandra's away this week.
15:01:22 <lmodemal[m]> Hello 👋 I'm lurking today!
15:01:31 <ariordan> #chair acozine
15:01:31 <zodbot> Current chairs: acozine ariordan
15:01:37 <lmodemal[m]> Hello everyone!
15:01:53 <ariordan> #topic opening chatter
15:01:53 <lmodemal[m]> Hi acozine !
15:02:13 <acozine> Hi lmodemal!
15:02:13 <ariordan> Hi acozine !
15:02:23 <acozine> and ariordan - Hi!
15:02:43 <ariordan> It's a surprisingly sunny day here.
15:03:23 * dericcrago waves
15:03:24 <acozine> heh, we got your usual weather - chilly and damp, though not actively raining
15:03:35 <ariordan> You can keep it :)
15:04:35 <acozine> heh, not for long . . . this is the midwest, don't forget, we don't have the ocean to moderate our weather, so snow and subzero (F) temps are on their way soon
15:05:02 <acozine> #chair deric.crago
15:05:02 <zodbot> Current chairs: acozine ariordan deric.crago
15:07:33 <ariordan> Before we start, would anyone else like to be furniture?
15:07:44 <acozine> I see a bunch of folks following along . . .
15:08:13 <ariordan> We'll get started then.
15:08:17 <acozine> it's totally fine to lurk, but "being furniture" is easy too
15:08:38 <ariordan> #topic Action item review
15:09:20 * acozine has a faint recollection of volunteering to do something at some point . . . and hopes there's a written record of it
15:09:46 <ariordan> Glad to know that this happens to someone else.
15:10:15 <ariordan> We merged the PR  that migrated the AWS collection docs from the Scenario guide
15:10:53 <ariordan> I created a PR to update the boilerplate wording for module docs: https://github.com/ansible-community/antsibull/pull/318
15:11:09 <acozine> oh, right, that was it - I was going to rebase that, and I did! phew
15:13:49 <ariordan> The aim of the boilerplate text PR is to avoid suggesting that the user needs to install the collection if they've installed ansible package
15:14:28 <ariordan> Feel free to reword it. I thought it best to have a PR to edit than to be swithering over the perfect phrase.
15:15:13 <acozine> The trouble with the specific change is that the template can be used with any collection in any context. We primarily see the template used on docs.ansible.com, but we cannot guarantee that that's the only place it will be used
15:15:44 <acozine> Can we add some logic that says "if the destination for this page is docs.ansible.com/ansible/, add this line"?
15:16:37 <acozine> On docs.a.c we only publish docs for collections that are included in the `ansible` package
15:16:59 <acozine> but the way the PR is currently written, that notice will show up everywhere
15:17:42 <ariordan> OK.
15:18:23 <acozine> part of the idea for antsibull was to support partners and developers who want to publish their own docs elsewhere
15:18:45 <ariordan> #action ariordan to update boilerplate text PR https://github.com/ansible-community/antsibull/pull/318
15:20:49 <ariordan> Other action item: we're working on backporting to the stable-2.12 branch.
15:21:18 <ariordan> Any other comments on action items?
15:21:53 <ariordan> cyb-clock-clone says we are  20 minutes into the meeting
15:23:01 <ariordan> #topic Updates on ongoing work
15:26:20 <acozine> what's our first update?
15:26:38 <ariordan> devel docs - continue to use 'devel' branch or move to the proposed interim (slightly more stable) branches coming soon?
15:27:34 <acozine> is there an issue somewhere that details what the new branch will /will not include, or a proposed workflow?
15:28:16 <ariordan> I don't think there is.
15:28:36 <acozine> the traditional workflow was: open PR, get it to pass CI, merge to `devel`, let the community try out the new functionality, file issues and fix as needed
15:28:46 <acozine> sounds like the "new devel" is going to be more experimental
15:29:26 <acozine> but without knowing how functionality moves from devel to the new semi-stable branch, it's hard to know which we should be documenting
15:30:13 <acozine> will the core team add features to "new devel" that might get thrown away?
15:30:57 <ariordan> The traditional workflow is pretty standard for open source, I assume. This is a big change. Are there advantages?
15:31:58 <ariordan> cyb-clock-clone says we are 30 minutes into the meeting
15:32:14 <acozine> we'd have to ask the people who are advocating for the change
15:32:44 <acozine> it would offer more flexibility, and a way to add major new features incrementally
15:32:56 <felixfontein> o/
15:33:05 <felixfontein> (sorry, was busy in a meeting earlier...)
15:33:07 <acozine> because you could have a list of "to do this bit thing, we'd have to change these six little things"
15:33:16 <acozine> and then merge items 1-4 separately
15:33:28 <ariordan> I'll put it on next week's agenda with some supporting links.
15:33:37 <acozine> during that period, devel might be "broken" for certain things
15:33:48 <ariordan> #chair felixfontein
15:33:48 <zodbot> Current chairs: acozine ariordan deric.crago felixfontein
15:33:51 <acozine> hey felixfontein
15:34:09 <acozine> but broken in a "yeah, we know" kind of way
15:34:33 <acozine> it would be a big change from what we've done in the past
15:35:17 * acozine looks back at her own typo, shakes her head
15:35:29 <acozine> s/ "to do this bit thing"/"to do this big thing"/g
15:36:14 <ariordan> Perhaps we need to teach the bot to run sed !
15:36:36 <acozine> better you than me, ariordan
15:36:57 <felixfontein> hehe :)
15:37:06 <ariordan> I'd need to learn sed properly myself, first.
15:38:21 <ariordan> Sandra created an issue to discuss adding community-contributed examples to a repo.
15:38:23 <ariordan> https://github.com/ansible-community/community-topics/issues/39
15:40:41 <acozine> nice!
15:41:11 <ariordan> There's a suggestion in the issue for repo names in ansible-community:
15:42:12 <ariordan> Community-examples or ansible-examples. Any thoughts?
15:42:48 <ariordan> There's already an ansible-examples in the Ansible hithub.
15:43:01 <acozine> Based on experience with the old config examples, users tend to look more at examples if they're examples of something specific
15:43:25 <acozine> my vote would be to start with a smaller set of examples
15:43:48 <ariordan> Sounds good.
15:44:02 <acozine> and call it something like `template_examples` or `filter_examples` or `how_to_get_the_data_snippet_your_playbook_needs` or something
15:44:38 <acozine> `finding_the_needle_in_the_JSON_haystack`, maybe?
15:45:20 <acozine> not really, but that's the kind of thing people search for, and don't necessarily expect to find in a repo called `community-examples`
15:46:02 <ariordan> OK, I'll add a comment in the issue.
15:46:23 <acozine> or maybe "can't be bothered to search for in a generic repo" is a better description
15:47:04 <ariordan> "I'd like the docs to read my mind and tell me what I need to do" would be a great hit.
15:47:11 <acozine> heh, yep
15:47:32 <ariordan> cyb-clock-clone says we are 45 minutes into the meeting
15:49:08 <acozine> Can we look at https://github.com/ansible/ansible/pull/75695?
15:49:08 <ariordan> action: ariordan to add comment in Community-contributed examples issue https://github.com/ansible-community/community-topics/issues/39
15:51:03 <acozine> The title of PR 75695 came from the branch name, it's really about allowing dropdowns in the Ansible docs
15:52:07 <ariordan> There's a comment in it about the Sphinx version needed.
15:53:16 <ariordan> #topic Allowing dropdowns in Ansible docs
15:53:36 <acozine> Ergh, yeah. We need to make bcoca's most recent innovations pass CI before we can upgrade the Sphinx version used in the test suite.
15:54:13 <acozine> I'm also curious if anyone has tried the test page with a variety of browsers/settings
15:54:53 <acozine> it feels like the kind of change that might spark a lot of "in OddBrowser this page doesn't work" comments
15:55:04 <acozine> In my browsers, it looks awesome
15:55:11 <acozine> but I'm using really mainstream stuff
15:55:13 <felixfontein> acozine: which page exactly? we have a browserstack account at work, I can look at it in a variety of browsers using that
15:55:35 <acozine> felixfontein: http://docs.testing.ansible.com/ansible/devel/user_guide/become.html#administrative-rights
15:56:00 <acozine> The `Task` and `Task output` sections under `Administrative rights`
15:56:15 <felixfontein> btw: https://caniuse.com/details
15:57:49 <acozine> heh, Internet Explorer
15:59:26 <acozine> I can think of a bunch of places in the rst docs where that expand/collapse would really help readability
15:59:37 <acozine> and I'd be happy to open some PRs
15:59:56 <acozine> but I don't want to do the work and then find out that part of the community hates it
16:00:04 <acozine> and we back out the changes
16:00:41 <ariordan> #action Add comment about testing browser and settings to https://github.com/ansible/ansible/pull/75695
16:01:22 <ariordan> cyb-clock-clone says we are 60 minutes into the meeting
16:02:11 <ariordan> I agree about that the expand / collapse would help readability.
16:02:56 <acozine> ariordan: comment added https://github.com/ansible/ansible/pull/75695#issuecomment-941151233
16:02:56 <ariordan> Thanks.
16:04:08 <ariordan> Before we go, there's an item in Open Floor.
16:04:36 <dericcrago> I have something for open floor as well
16:04:51 <ariordan> I created about 35 really easy issues for Hacktoberfest.
16:05:02 <felixfontein> I tried with a range of browsers, mostly once which shouldn't support it, and there it often doesn't look so great, but you can see all the content
16:05:14 <felixfontein> (I even tried IE 8 :) )
16:05:49 <ariordan> I assumed there'd be the occasional PR and that I'd end up finishing them in November, but all the issues had PRs within a day.
16:06:03 <ariordan> All are merged except for one longer one.
16:06:06 <acozine> felixfontein: thanks! having the content available is more than half the battle
16:06:21 <acozine> ariordan: the Ansible community steps up!
16:06:21 <ariordan> Thanks, Felix Fontein
16:06:47 <ariordan> #topic Open Floor
16:07:14 <ariordan> deric.crago:  You had something for open floor?
16:07:27 <dericcrago> indeed I do :)
16:07:35 <dericcrago> writing it up, one sec
16:09:21 <dericcrago> now that ansible-core is python >= 3.8, should https://github.com/ansible/ansible/blob/devel/docs/docsite/Makefile#L48 be either `PYTHON=python3` or `PYTHON ?= python` ?
16:11:11 <felixfontein> python3 sounds sensible to me
16:12:03 <acozine> the generic version is more maintainable - someday there may be python4
16:12:28 <acozine> what do we gain by specifying a version there?
16:12:41 <felixfontein> if the transition python3 -> python4 goes the same way as 2 -> 3, it will likely take some time until ansible actually works with python4
16:12:53 <acozine> heh, very true
16:13:13 <acozine> I'm just thinking, doesn't `PYTHON=python` work across versions?
16:13:32 <felixfontein> it depends on what your system's default Python is
16:13:40 <felixfontein> for modern system it should be Python 3 anyway :)
16:13:49 <acozine> heh, the dreaded "should"
16:13:51 <dericcrago> not unless `python` is symlink'd to `python3`
16:14:25 <acozine> so if we leave it the way it is, the script will fail unless the user has python3 as the default?
16:14:51 <acozine> if that's the case, then updating would be helpful
16:15:01 <dericcrago> correct, I ran into this with the ansible-core build on ubuntu
16:15:12 <dericcrago> (for 2.12.0b1)
16:15:31 <dericcrago> I wasn't just looking for things to change ;)
16:15:36 <acozine> heh
16:16:12 <acozine> okay, sounds like a good idea
16:17:10 <dericcrago> `PYTHON ?= python` is probably the least disruptive, doesn't change current behavior at all, just allows people to override
16:19:07 <acozine> sounds great
16:19:26 <dericcrago> for example, that's what it is in https://github.com/ansible/ansible/blob/devel/Makefile#L37
16:20:10 <ariordan> That makes sense.
16:20:16 <dericcrago> ok, I can submit a PR for that
16:20:34 <ariordan> Thanks, deric.crago
16:21:06 <acozine> I need to run. Thanks, folks!
16:21:09 * acozine waves
16:21:10 <ariordan> Any other topics to discuss? We're 80 minutes into the meeting.
16:21:16 <acozine> #unchair acozine
16:21:16 <zodbot> Current chairs: ariordan deric.crago felixfontein
16:21:24 <ariordan> Bye, acozine !
16:25:03 <ariordan> Bye everyone. Thanks for attending.
16:25:15 <ariordan> #endmeeting