14:30:06 <gundalow> #startmeeting Ansible Documentation Working Group
14:30:06 <zodbot> Meeting started Tue Oct 30 14:30:06 2018 UTC.
14:30:06 <zodbot> This meeting is logged and archived in a public location.
14:30:06 <zodbot> The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:30:06 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:30:06 <zodbot> The meeting name has been set to 'ansible_documentation_working_group'
14:30:32 <gundalow> #chair acozine samccann bizonk dfed thedoubl3j
14:30:32 <zodbot> Current chairs: acozine bizonk dfed gundalow samccann thedoubl3j
14:31:25 <gundalow> Anyone else around?
14:31:40 <GreNME> <--- JLieske
14:31:46 <gundalow> #chair GreNME
14:31:46 <zodbot> Current chairs: GreNME acozine bizonk dfed gundalow samccann thedoubl3j
14:32:03 <gundalow> #Info First meeting, will have a look at some PRs
14:32:13 <GreNME> I think the whole GS team is around
14:32:28 <acozine> should we do introductions first?
14:32:43 <gundalow> acozine: Sure, if you do `#info ...` then it will go into the main log
14:32:56 <gundalow> (everything is logged, #info just makes it stand out more)
14:33:03 <dfed> ahoy bcoca.
14:37:17 <acozine> #info my name is Alicia Cozine, I'm the lead tech writer for Ansible
14:37:17 * bcoca waves
14:37:17 <GreNME> sup dawg
14:37:17 <GreNME> <-- Lieske
14:37:17 <acozine> bcoca: since this is the first public IRC meeting, I thought we'd do introductions
14:37:17 <acozine> for posterity, you know
14:37:17 <bizonk> Sounds good!
14:37:17 <dfed> #info I am David F, I am on the Ansible BU Product Management team.
14:37:17 <gundalow> #info I'm gundalow, I look after the Ansible Community
14:37:17 <bcoca> #info I'm Brian Coca and have been so.. er a core developer for ansible
14:37:17 <GreNME> I'm John L, on the Product Management team (getting started)
14:37:17 <samccann> #info I'm samccann, I handle docs efforts for Ansible network
14:37:18 <thedoubl3j> #info my name is Jake Jackson, I am a senior product field engineer, working with the getting started team at Ansible
14:37:18 <bizonk> #info I am Bianca H, I work on the Getting Started team as well, as Sr Product Field Engineer.
14:37:18 <gundalow> Ace, that everybody
14:37:18 <gundalow> #topic PR review
14:39:38 <gundalow> #info Will go through some PRs to see what we can merge
14:39:38 <acozine> we've got two open PRs related to RabbitMQ docs
14:39:38 <gundalow> #info https://github.com/ansible/ansible/pull/46504 RabbitMQ documentation suggests that deleting queues/exchanges is not implemented, but it is
14:39:38 <gundalow> hum, that looks straight forward
14:39:38 <gundalow> +1 to merge
14:39:38 <bizonk> +1
14:39:38 <dfed> +1 looks good to merge
14:39:38 <thedoubl3j> +1
14:39:39 <acozine> for my edification, can anyone point at the line in the python where the delete action is implemented?
14:39:39 <acozine> s/line/lines, since there are two modules?
14:39:55 <gundalow> https://github.com/ansible/ansible/blob/f3c05ccc37587530be1aa5271baad0af517efcda/lib/ansible/modules/messaging/rabbitmq_exchange.py#L203
14:40:10 <dfed> it's just a deletion, click on the "files changed" tab
14:40:24 <acozine> ah, cool, yep, "requests:delete"
14:40:50 <acozine> dfed: yeah, I just wanted to double-check that the docs really do reflect the code correctly
14:40:56 <gundalow> #action gundalow to create backport
14:41:03 <gundalow> Next PR?
14:41:04 <dfed> sure thing,
14:41:32 <acozine> https://github.com/ansible/ansible/pull/46064
14:41:55 <acozine> moves the RabbitMQ modules into a sub-directory
14:42:00 <gundalow> #info https://github.com/ansible/ansible/pull/46064 BOTMETA: Move rabbitmq modules to own directory
14:42:11 <acozine> oops, missed the "info" bit
14:42:23 <dfed> LOL it takes a bit to get used to the meetbot commands
14:42:34 <acozine> this way we'll have room for other messaging options
14:42:42 <dfed> topic, info and action are the most used ones.
14:42:48 <bizonk> Plus some wording/formatting changes
14:43:25 <acozine> yeah, while dag was moving the files he tidied them up
14:43:41 <acozine> ah, needs rebasing
14:43:52 <gundalow> Apart from rebase looks good to me
14:44:57 <acozine> welcom akshay196
14:45:11 <acozine> I can haz spellink
14:45:12 <akshay196> acozine, Thank you :)
14:45:37 <acozine> we're in the midst of the docs community meeting, reviewing some open PRs
14:45:49 <gundalow> #chair akshay196
14:45:49 <zodbot> Current chairs: GreNME acozine akshay196 bizonk dfed gundalow samccann thedoubl3j
14:46:22 <acozine> any other thoughts on the RabbitMQ-move PR?
14:47:10 <dfed> yeah rebase and it's good
14:47:21 <samccann> looks okay to me.
14:47:27 <acozine> #action acozine to rebase PR 46064
14:47:28 <bizonk> Looks good!
14:47:38 <gundalow> #agreed rebase & merge BOTMETA: Move rabbitmq modules to own directory #46064
14:47:44 <gundalow> next (#info)
14:47:49 <acozine> awesome!
14:47:57 <acozine> okay, we've got two new simple ones
14:48:16 <dfed> oh I forgot about hashtag agreed
14:48:32 <dfed> see gundalow is making me remember all sorts of meetbot goodness
14:48:43 <gundalow> #action acozine to merge https://github.com/ansible/ansible/pull/47818 (2.7 backport)
14:48:49 <thedoubl3j_> reconnecting (I timed out)
14:48:58 <acozine> #info https://github.com/ansible/ansible/pull/47816/files would change description of VLAN parameters
14:49:03 <gundalow> #chair thedoubl3j_
14:49:03 <zodbot> Current chairs: GreNME acozine akshay196 bizonk dfed gundalow samccann thedoubl3j thedoubl3j_
14:49:54 <gundalow> +1 good improvement
14:50:00 <samccann> +1
14:50:09 <bizonk> I think that new wording makes things more clear, +1
14:50:28 <acozine> merged
14:50:46 <gundalow> #action gundalow to backport  https://github.com/ansible/ansible/pull/47816/files would change description of VLAN parameters
14:50:51 <gundalow> bizonk: did you have one?
14:50:56 <bizonk> Yes
14:51:28 <bizonk> #info https://github.com/ansible/ansible/pull/47778 This adds a link so that contributors have an easier time finding additional information on PRs
14:52:21 <acozine> +1 helps users find more info
14:52:37 <gundalow> +1
14:52:37 <samccann> +1 agreed
14:52:47 <theodubl3j> +1
14:52:56 <GreNME> +1
14:55:09 <theodubl3j> <---can't type but I will remain so I don't get behind
14:55:09 <acozine> heh, I've tried twice to merge 47778, are multiple people trying to merge it?
14:55:09 <theodubl3j> still showing open on my end
14:55:09 <acozine> fourth time was apparently the charm
14:55:09 <acozine> merged
14:55:24 <bizonk> :D
14:55:25 <samccann> maybe we start the next meeting with an assigned merger person
14:55:33 <acozine> samccann: that's a good idea
14:55:36 <samccann> (or maybe it was just github gremlins)
14:55:44 <bizonk> Great idea!
14:55:51 <gundalow> samccann: Good idea
14:55:56 <theodubl3j> had a question about how/when the deprecation of with_ for loops would be implemented into docs.
14:56:04 <gundalow> also it's fine to just #action it all, then that person can merge & dobackports
14:56:09 <samccann> ...and an assigned backporter... I know I get 'in the groove' when doing those and they go faster in batches
14:56:29 <acozine> theodubl3j:  let's talk about that
14:56:40 <theodubl3j> for all modules etc. I know that we updated the playbook guides etc but when/how do we want modules to update?
14:56:54 <acozine> we've updated some, but not all
14:57:00 <theodubl3j> ok
14:57:06 <theodubl3j> only reason I brought it up was https://github.com/ansible/ansible/pull/47244
14:57:09 <acozine> the issue is that with_* is still a viable option
14:57:23 <gundalow> #topic with_ vs loops docs
14:57:26 <gundalow> bcoca: may want to join in
14:57:30 <gundalow> #chair bcoca
14:57:30 <zodbot> Current chairs: GreNME acozine akshay196 bcoca bizonk dfed gundalow samccann thedoubl3j thedoubl3j_
14:57:56 <theodubl3j> that it is, that is why I asked, didn't know how and when we would want to update the module docs that had those examples in them
14:58:01 <acozine> theodubl3j: we've seen quite a few PRs changing "with_*" to "loop"
14:58:36 <acozine> the consensus is that for simple examples, where it's just with_items, then a list of items, we should change to loop
14:58:36 <gundalow> I think there are a few parts to this, which we've talked about in the past
14:58:54 <gundalow> 1) What should the examples (in rst & module.EXAMPLES) use
14:59:12 <gundalow> 2) Where/how should we detail how to move from `with_` to `loops`
14:59:33 <gundalow> 3) Is there anycase where `with_` still make sense
14:59:59 <acozine> We have some content for 2) here: https://docs.ansible.com/ansible/latest/porting_guides/porting_guide_2.5.html#migrating-from-with-x-to-loop
15:00:00 <felixfontein> how about with_dict? that's pretty simple to translate
15:00:53 <gundalow> #chair felixfontein
15:00:53 <zodbot> Current chairs: GreNME acozine akshay196 bcoca bizonk dfed felixfontein gundalow samccann thedoubl3j thedoubl3j_
15:00:57 <gundalow> felixfontein: Welcome :)
15:02:00 <theodubl3j> aconzine: ok cool, this PR references all the way back for 2.5. with_* deprecates when? 2.9 right?
15:02:37 <gundalow> I don't know if we will ever remove `with_`
15:02:43 <acozine> theodubl3j: we have not deprecated with_*
15:02:47 <theodubl3j> oh
15:02:54 <acozine> we also have this page: https://docs.ansible.com/ansible/latest/user_guide/playbooks_loops.html
15:02:59 <gundalow> As it's been used waaaaaaaaay too much
15:02:59 <theodubl3j> my apologies, stuck in my head that it was being deprecated.
15:03:11 <gundalow> theodubl3j: The original plan was that it would be
15:03:14 <bizonk> Oh so it's more of a "better practices" sort of thing?
15:03:24 <gundalow> If you are confused then others will be
15:04:34 <acozine> for folks writing new playbooks/roles, should we encourage them to use loop?
15:05:08 <GreNME> good question
15:05:20 <theodubl3j> that is what I was thinking aconzine. I was wondering what the right way to point people to was.
15:05:25 <bizonk> Looks like that's something to explicitly state in that page (that the current plan is to NOT deprecate it), unless like acozine mentioned, we want to actively encourage people to use "loop"
15:06:06 <gundalow> https://github.com/ansible/ansible/issues/47703#issuecomment-433946762
15:06:14 <acozine> if we want to encourage folks to use loop, then we can replace with_* in the 2.8 docs at least
15:06:21 <gundalow> #info `with_` syntax is not obsolete, and is not deprecated.
15:07:38 <bcoca> we do plan on deprecating it, but long way from there
15:07:43 <bizonk> I personally find `with_` to be easier to use, since it directly addresses what the variables are that it's referencing (e.g. `with_items`)
15:08:00 <bcoca> with_items is problematic as it is deceptive
15:08:10 <bcoca> it has an implicit |flatten(1)
15:08:18 <bcoca> most people think it works like with_list:
15:08:25 <bcoca> ^ which is what loop:  is equivalent to
15:08:28 <dfed> ok so how should docs make that more clear?
15:08:50 <acozine> I think that playbooks_loops page could do a better job of describing the current state
15:08:56 <dfed> should we mention the flatten?
15:09:02 <bcoca> unsure, the 'flatten' part has been in docs for long time, yet no one seems to read it
15:09:13 <gundalow> #info https://github.com/ansible/ansible/pull/47364#issuecomment-431472984
15:09:17 <dfed> that would imply we need to revisit how it is in the docs.
15:09:43 <acozine> gundalow: thanks, that's a great source
15:09:46 <gundalow> ^ link has the when to/when not to use
15:09:55 <gundalow> #info when to, and when not to use `loop`  https://github.com/ansible/ansible/pull/47364#issuecomment-431472984
15:10:01 <dfed> hm yesl
15:10:14 <acozine> #action acozine to update the playbooks_loops page with sivel's comments
15:10:21 <dfed> I like that.
15:10:56 <acozine> once we have an updated page, we can merge or close the open PRs that change with_* in accordance with those guidelines
15:11:12 <gundalow> Sounds like a plan
15:11:54 <acozine> can we look at another open docs PR?
15:11:58 <gundalow> acozine: theodubl3j bizonk Anything else on that?
15:12:01 <gundalow> acozine:  Sure
15:12:04 <gundalow> #topic PR review
15:12:50 <acozine> anybody want to add to the discussion on loop?
15:13:10 <bizonk> Before we get off the topic of loops, just wanted to add something:
15:13:13 <bizonk> `flatten` has been in the docs but I haven't seen that used very frequently in playbooks
15:13:14 <felixfontein> sivel's comments are really useful
15:13:31 <bizonk> I don't think I've actually ever seen it in playbooks
15:13:35 <felixfontein> especially "Any with_ statement, that requires using lookup within loop should not be converted"
15:13:53 <bizonk> So either emphasizing its usage/explaining it further in the docs would be good, imo
15:14:10 <GreNME> yeah ditto
15:14:23 <acozine> felixfontein: yeah, it's a really clear guideline, and with an example or two, it should give us an easy way to evaluate existing examples in module docs, etc.
15:14:37 <acozine> bizonk: agreed that flatten isn't common
15:15:35 <theodubl3j> imo, I wasn't up to date on how and when things would be changing, I think sivel's comments are super helpful so I won't echo any further on that as it would be repeating others.
15:16:25 <acozine> bcoca: I missed your comment about an "implicit flatten" - do you have examples where that would trip a user up?
15:17:08 <bcoca> https://gist.github.com/bcoca/b1f3d8d6e802663b0e818959b2d547e6
15:17:26 <bcoca> ^ change to with_list or 'loop' and you get 3 items, vs 4 with with_items
15:17:37 <bcoca> 90% of usage of with_items really was meant to be with_list
15:17:48 <acozine> ah, that is a great illustration of the difference
15:18:12 <acozine> definitely great content for the playbooks_loops page
15:19:26 <acozine> other ideas about loops, with_*, or how to document them?
15:19:44 <acozine> welcome Xaroth:
15:19:48 <Xaroth> o7
15:20:06 <acozine> we're in the home stretch of the docs working group meeting
15:20:24 <acozine> #topic squeezing in a last PR review
15:21:08 <acozine> https://github.com/ansible/ansible/pull/47767 - updates the output shown for ansible facts from Ansible 1.4 to Ansible 2.7
15:21:35 <acozine> I threw a bunch of other updates in while i was there, though the page could still use more love
15:21:41 <gundalow> #chair Xaroth
15:21:41 <zodbot> Current chairs: GreNME Xaroth acozine akshay196 bcoca bizonk dfed felixfontein gundalow samccann thedoubl3j thedoubl3j_
15:21:47 <gundalow> Xaroth: Hello again :)
15:21:51 <Xaroth> :)
15:21:53 <acozine> felixfontein: and samccann have already reviewed
15:23:00 <theodubl3j> +1 update was needed and addresses everything, looks great to me
15:23:03 <dfed> wait we were still showing facts from ansible 1.4 runs?
15:23:13 <dfed> wow.  yeah good update!@
15:23:25 <acozine> dfed: yep
15:23:36 <samccann> +1
15:23:54 <dfed> 1.4 was released november of 2013, just after I first started.
15:24:07 <dfed> I blame sivel.
15:24:15 <sivel> I would too
15:24:26 <bizonk> +1 for PR 47767
15:24:29 <dfed> +1 acozine that looks good
15:24:53 <acozine> excellent!
15:24:59 <bizonk> I have a couple more suuuuper quick ones if we have time...
15:25:02 <acozine> anybody else have PRs they'd like to bring to the floor?
15:25:09 <acozine> bizonk: great
15:25:15 <Xaroth> +1 could only find a minor nit-pick (ipv6 fact doesn't show anything, which makes sense since a lot of systems don't have active ipv6 configs)
15:26:07 <acozine> Xaroth:  do you have some sample output for ipv6 we could add?
15:26:31 <acozine> more is better when it comes to examples
15:27:57 * gundalow doesn't have IPv6 on any of his systems
15:28:20 * acozine doesn't have even a tenth of the stuff in that example output on any of hers
15:28:33 <Xaroth> let me check my cluster, I think we have it disabled internally
15:28:41 <gundalow> Thanks :)
15:28:47 <acozine> Xaroth: awesome
15:29:00 <felixfontein> we got IPv6 on all our servers, but I don't have any (local) internet connection which has IPv6...
15:29:42 <dfed> I could create a lab to do it later this week, but honestly someone's gonna have this snippet to add surely before I get to it
15:30:36 <gundalow> We can always add it later
15:30:47 <acozine> Xaroth: we'll probably merge the current PR today, but if you get that output after, another PR would be very welcome
15:30:56 <gundalow> +1
15:30:59 <dfed> +1
15:31:00 <Xaroth> +1
15:31:16 <theodubl3j> +1
15:31:31 <bizonk> Before we close out...
15:31:34 <bizonk> #info https://github.com/ansible/ansible/pull/47664/files This is very sweet, but I think it's one to close (changes "Ansible is an IT automation tool" to "Ansible is an great IT automation tool" [sic])
15:31:52 <dfed> LOL +1 we don't need to get into commentary
15:32:00 <bizonk> :)
15:32:17 <acozine> bizonk: agreed, but maybe we could notify marketing and have them tweet something about it or otherwise give the person some love?
15:32:41 <theodubl3j> +1 nice of them and aconzine: that sounds like a great idea
15:32:52 <Xaroth> acozine:  I have a few systems that show ipv6 info, but no ansible_default_ipv6; since we have no ipv6 default gateway. Will check when I'm in the office tomorrow to see if I can find any stragglers that do.
15:33:12 <bizonk> Awww that does sound like a good idea, acozine!
15:33:13 <acozine> that PR looks like a great opportunity for a little PR (pun intended)
15:33:19 <bizonk> lol
15:33:25 <Xaroth> +1 on that idea, acozine.
15:33:28 <bizonk> +1
15:33:28 <acozine> Xaroth: awesome, thanks
15:33:41 <dfed> +1
15:33:52 <acozine> we're at time . . . thanks everyone for attending, for chatting, for working to make the docs better!
15:34:19 <bizonk> Thank you!
15:34:24 <dfed> thanks y'all.
15:34:32 <theodubl3j> thanks all
15:34:35 <bizonk> I will alert Marketing about 47664
15:34:39 <gundalow> Thanks
15:34:42 <samccann> thanks everyone!
15:34:49 <acozine> bizonk: awesome
15:34:51 <dfed> bizonk: make that an action in the meeting pls.
15:35:15 <gundalow> #info Agenda has been created https://github.com/ansible/community/issues/389
15:35:17 <bizonk> #action bizonk to alert Marketing about Docs PR 47664
15:35:25 <gundalow> Thanks y'all
15:35:26 <theodubl3j> someone push close on it?
15:35:29 <gundalow> #endmeeting