14:31:50 <samccann> #startmeeting Docs Working Group aka DaWGs
14:31:50 <zodbot> Meeting started Tue Nov 19 14:31:50 2019 UTC.
14:31:50 <zodbot> This meeting is logged and archived in a public location.
14:31:50 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:50 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:50 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:32:05 <samccann> who's around to talk docs??
14:33:44 <samccann> philosophical question - if a dawgs meeting facilitator burns her tongue on hot tea and nobody is around to hear her complain...did it still hurt?
14:34:14 <acozine> ow . . . unfortunately, I'm guessing the answer is yes
14:34:26 <samccann> @gundalow @felixfontein @Pilou @alongchamps?  anyone around?
14:34:29 <samccann> hah!
14:34:32 <samccann> #chair acozine
14:34:32 <zodbot> Current chairs: acozine samccann
14:34:54 * gundalow waves
14:34:55 <samccann> and yep, the answer is yes... it hurts
14:35:03 <samccann> #chair gundalow
14:35:03 <zodbot> Current chairs: acozine gundalow samccann
14:35:03 <acozine> shaps: tributarian Xaroth you folks talking docs today?
14:35:15 <samccann> welcome gundalow!!!
14:35:45 <samccann> #link agenda - https://github.com/ansible/community/issues/389#issuecomment-552947619
14:36:31 <tributarian> acozine: can’t make it today.
14:36:53 <acozine> tributarian: bummer, hope you're doing something fun!
14:37:10 <alongchamps> I'm here
14:37:29 <acozine> #chair alongchamps
14:37:29 <zodbot> Current chairs: acozine alongchamps gundalow samccann
14:37:36 <acozine> welcome alongchamps!
14:38:58 <acozine> looks like the agenda today is PRs and issues and more PRs
14:39:28 <samccann> fun times!!
14:40:06 <samccann> should we start with a call for anyone who has a PR they want us to discuss?
14:40:24 <acozine> +1
14:40:41 <acozine> I see two specific PRs or issues listed on the agenda
14:41:01 <samccann> ok let's start there
14:41:06 <acozine> anybody here for either #64888 or #63982?
14:41:23 <xuxiaowei0512_> +1
14:42:11 <samccann> Welcome xuxiaowei0512_
14:42:23 <xuxiaowei0512_> Thanks.
14:42:46 <samccann> anyone have comments/suggestions on https://github.com/ansible/ansible/pull/63982 ?
14:43:53 <samccann> it's passing shippable so ready to merge unless someone sees anything?
14:44:23 <acozine> and it's got a shipit
14:44:29 <samccann> okay imma merge then.
14:44:49 <samccann> thanks  xuxiaowei0512_
14:44:58 <acozine> excellent!
14:45:21 <samccann> next PR is -https://github.com/ansible/ansible/pull/64888
14:45:31 <acozine> this looks like a good addition to me
14:46:16 <samccann> +1 as well
14:46:18 <xuxiaowei0512_> cool,  thank you for merging.
14:46:31 <samccann> imma merge that as well unless someone screams in the next few seconds...
14:46:34 <acozine> I would hope that most people would recognize the `diff` section for what it is, but since we document other values like `failed`, I think we should document this one too
14:46:43 <samccann> yep
14:46:59 <acozine> go for it samccann
14:47:05 <alongchamps> +1
14:47:08 <samccann> merged
14:47:16 <acozine> \o/
14:47:33 <acozine> would adding examples to that page be useful?
14:47:45 <acozine> (not today, but in general)?
14:48:21 <acozine> here's the page as it looks now: https://docs.ansible.com/ansible/devel/reference_appendices/common_return_values.html
14:48:39 <felixfontein> sorry, I'm only partially around
14:48:54 <acozine> ooh, the entry for `skipped` is missing a period
14:49:01 <acozine> that kind of stuff bugs me
14:49:05 <felixfontein> thanks for merging the PR!
14:49:33 <felixfontein> examples would be nice I think
14:50:06 <acozine> that seems like a good `easyfix` issue, too
14:50:17 <felixfontein> (that stuff bugs me as well, it's mostly time constraints and other interests as well that I don't spend 100% of my time correcting such things ;) )
14:50:27 <samccann> :-)
14:51:17 <samccann> what we need to do is tie into a set of college kids in their early programming classes - use it as a lesson to learn git (and fix spelling/punctuation issues) :-)
14:51:25 <acozine> felixfontein: heh, we need to leave some things for new docs folks to cut their teeth on
14:51:33 <acozine> samccann: that is a brilliant idea
14:51:56 <acozine> meanwhile I'm creating an issue
14:52:45 <samccann> I think that was partially the idea of Hactoberfest/Doctober ... but first time I've been involved with either so didn't quite get the traction we could have
14:54:26 <acozine> This could use some more detail, but it's a placeholder at least: https://github.com/ansible/ansible/issues/65062
14:54:47 <samccann> I wonder if we could do something more than once a year though - like every few months, host a 'welcome to ansible development' session where folks are available to help with the 'basics' that might be holding up folks looking to dig in a bit (like git, setting up tools etc)
14:54:57 <samccann> tho i'm straying from Docs there, but anyway
14:55:55 <samccann> did you want an `easyfix` on that issue?
14:56:29 <acozine> good question - do we think it has enough information for it to be an easy fix?
14:56:56 * acozine with the time change, doesn't bring her most awake brain to the DaWGs meetings
14:57:23 <samccann> well it's a clear issue, but how would someone find examples of each type? I guess that's what makes it tricky
14:58:07 <samccann> So maybe we need to add a couple of examples in the issue itself and say someone can create a PR with whatever examples they have (doesn't have to be the full set)?
14:58:14 <samccann> or is that obvious to the world?
14:58:34 <acozine> let's mark it easyfix and if folks have questions, maybe they'll find us here to ask
14:59:12 <acozine> alongchamps: I nominate you to pick the next PR for us to look at as a group
14:59:25 <alongchamps> uhhh hi
14:59:26 <alongchamps> :)
14:59:51 <acozine> there are lots to choose from ;-)
14:59:56 <alongchamps> actually just about to join another meeting
15:00:15 <acozine> heh, okay
15:00:24 <acozine> sorry, I didn't mean to put you on the spot
15:01:13 <samccann> #topic PR reviews
15:01:20 <samccann> (coming in late with that, but anyway)
15:01:24 <alongchamps> I went to the oldest ones in the list and they're 2.2, 2.3 versions
15:01:26 <samccann> #link https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs  open PRs
15:01:41 <acozine> alongchamps: yeah, we have some really old ones still hanging around
15:01:52 <alongchamps> so... merge or close without merging?
15:01:56 <alongchamps> I like getting rid of old stories :)
15:02:17 <acozine> getting rid of old stories is awesome
15:02:56 <alongchamps> 24370 looks good for that, it's for 2.4 which I'm pretty sure is out of support
15:03:33 <acozine> yep, we only maintain 2.7, 2.8, and 2.9 now
15:03:47 <alongchamps> 35817 is for 2.6
15:04:33 <samccann> for 24370 - looks like I tried to get it closed last year and that was rejected
15:04:39 <alongchamps> 37587 also is 2.6
15:04:51 <samccann> (it's a module, so not one we can make unilateral decisions on as well)
15:06:17 <alongchamps> is there any policy for old tickets, e.g. > 1 year that have been inactive
15:06:33 <acozine> alongchamps: unfortunately not that I know of
15:06:42 <acozine> I would be in favor of such a policy
15:06:47 <alongchamps> could that be a proposal brought up at the core meeting?
15:06:50 <samccann> yeah me too really
15:06:55 <acozine> +100
15:06:59 <alongchamps> since it's bigger than just #docs
15:07:09 <samccann> then again, won't they all just go away after everything is in collections?
15:07:22 <samccann> or will they still linger?
15:07:38 <acozine> samccann: they might . . . at least, the new module ones should, but the more we can close now, the happier I will be
15:07:39 * alongchamps still needs to catch up on collections
15:08:04 <acozine> most of the old PRs with the `docs` label include code as well as documentation
15:08:28 <acozine> the ones that are docs only we generally merge or close within a few weeks or months at most
15:09:44 <acozine> looking at the list, it's not as bad as i feared . . . we get into 2019 by the next-to-last page
15:10:01 <acozine> https://github.com/ansible/ansible/pulls?page=4&q=is%3Apr+is%3Aopen+label%3Adocs&utf8=%E2%9C%93
15:10:06 <samccann> anyone here know azure? this PR is adding an example, but I can't tell if it's a correct example or not - https://github.com/ansible/ansible/pull/65007
15:11:23 <acozine> hmmm, the syntax looks okay
15:11:49 <acozine> and with something that long, I suspect the person lifted it from a working playbook
15:12:06 <acozine> but I don't know anything about private blob files
15:12:39 <alongchamps> I don't know much about azure but the code _seems_ right
15:12:52 <samccann> ok it still has a `needs_triage` label so the core folks will likely take a look as well in their next triage
15:13:37 <acozine> where does the azure working group meet?
15:13:41 <samccann> here's a good one - https://github.com/ansible/ansible/pull/64855
15:13:42 <acozine> gundalow: do you know? ^^^
15:14:01 <samccann> (sorry, popped that in too soon in the middle of the azure discussion)
15:15:39 <acozine> I'm tempted to merge the Azure one
15:16:07 <acozine> but if we have a way to ping someone who knows more about the specifics of Azure, I'd do that first
15:16:42 <samccann> my calendar sez ansible-windows WG meets today at 3pm ET. Did you want to bring it there for comment first?
15:16:47 <acozine> cbudz: are you around?
15:17:19 <acozine> hm, the windows people may not know much about the Azure cloud
15:17:26 <acozine> I mean, they might, but not necessarily
15:17:34 <samccann> ah was thinking it was the same company..but yeah, maybe not
15:18:22 <samccann> https://github.com/ansible/community/wiki/Azure
15:18:28 <cbudz> Hi, yep i'm here
15:18:31 <samccann> they have an IRC channel here we can bring it to
15:18:42 <acozine> samccann: cool
15:20:30 <samccann> ok so now
15:20:33 <samccann> #link https://github.com/ansible/ansible/pull/64855
15:20:37 <gundalow> acozine: was in another meeting, which PR?
15:20:52 <samccann> This is updates to the ansible.cfg file
15:21:00 <acozine> gundalow: I was asking where the Azure WG meets . . . samccann found their IRC channel
15:22:07 <acozine> re: 64855 - cbudz were you suggested changes to the PR as it stands?
15:23:36 <cbudz> Yes, my recommendation would be to remove anything that's not in the context of an example, like [privilege_escalation] and allow anything that simply lists default values to live on the doc link that samdoran added
15:25:25 <samccann> does this file get installed w/ ansible?
15:25:46 <cbudz> I believe so
15:26:21 <samccann> so it needs to 'work' so to speak.
15:26:39 <samccann> just thinking out loud here a bit
15:27:17 <acozine> yes, like many sample config files, it shows mostly the defaults
15:27:57 <samccann> so as a user, I'd want to go to this file, and get hints on what I might want to change.  So for example, where it says `defaults` - a comment that says these are some parameters you may need to change. Uncomment if you want somethign other than the default values.  And then a pointer to the file cbudz mentions in his comment
15:27:59 <acozine> the privilege escalation section is a commonly-used set of options for config
15:28:40 <acozine> samccann: yes
15:29:20 <samccann> and then, everything should be default values. So if someone uncomments, they have to deliberately change the value or its still default (based on the OP comment that this is confusing to people)
15:29:23 <cbudz> Can privilege escalation be wrapped in some context to provide example usage?
15:29:32 <acozine> I think the sample config should include all the optional sections, at least, so users know they have them available
15:30:01 <samccann> agreed
15:30:43 <samccann> the sample file should have every available 'section' and then a comment on what that secdtion does, and pointer to relevant doc/appendix (if there is more than one... I haven't loooked)
15:30:57 <acozine> cbudz: so add a comment above the section header explaining what privilege escalation is for?
15:30:58 <samccann> and then list only the parameters/options most commonly changed
15:31:11 <samccann> I'd add it below so it's obvious it belongs in that section
15:31:27 <cbudz> @acozine, yes, essentially
15:31:29 <acozine> oh, another thing this file should point at is the page on general precedence
15:31:57 <acozine> cbudz: that seems like a good idea - establish a pattern for the file like:
15:32:29 <acozine> https://www.irccloud.com/pastebin/v8eYlcyS/
15:32:46 <acozine> heh, the comment should start with `#`, of course
15:32:47 <cbudz> yes, that would be ideal
15:32:49 <samccann> to me, the comment should be below the section header
15:32:56 <cbudz> yes
15:33:03 <acozine> ah, yes, that's better
15:33:33 <acozine> so my suggestion is that we merge the existing PR
15:33:53 <acozine> and then cbudz can work on the next iteration/improvement
15:34:00 <samccann> +1
15:34:06 <cbudz> that works for me
15:34:10 <acozine> awesome
15:34:49 <samccann> #agreed - will merge PR 64855 as is and cbudz will work on next iteration
15:35:12 <samccann> #action cbudz to continue improvements to ansible.cfg examples and comments
15:35:30 <samccann> (fingers crossed I actually did that correctly)
15:35:48 <samccann> we're 5 min over - any other last minute items?
15:35:53 <samccann> #topic Open Floor
15:36:46 <samccann> going once....
15:37:20 <samccann> going twice...
15:37:39 <acozine> thanks cbudz alongchamps felixfontein samccann gundalow
15:37:47 <cbudz> thanks all
15:38:01 <samccann> #endmeeting