15:34:52 <gundalow> #startmeeting Ansible Docs Working Group
15:34:52 <zodbot> Meeting started Tue Feb  5 15:34:52 2019 UTC.
15:34:52 <zodbot> This meeting is logged and archived in a public location.
15:34:52 <zodbot> The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:34:52 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:34:52 <zodbot> The meeting name has been set to 'ansible_docs_working_group'
15:34:52 <zodbot> samccann: Error: Can't start another meeting, one is in progress.
15:35:04 <gundalow> #chair samccann
15:35:04 <zodbot> Current chairs: gundalow samccann
15:35:07 <gundalow> lol, woops
15:35:14 <samccann> heh jinx!
15:35:36 <samccann> anyone else around for some docs fun?
15:35:42 <imack> hi
15:35:50 <alongchamps> I'm here; mostly watching along and getting a feel for things
15:35:53 <gundalow> #info Agenda https://github.com/ansible/community/issues/389
15:35:54 <imack> i am new to the work group
15:35:58 <gundalow> #chair imack alongchamps
15:35:58 <zodbot> Current chairs: alongchamps gundalow imack samccann
15:36:20 <gundalow> imack: Welcome :) How did you hear about the working group, what you like to get out of it?
15:36:38 <gundalow> (this is all very informal, so feel free to jump in at any point during the discussions)
15:37:07 <imack> i have attended one webinar on how to get into contributing for ansible, and here i am :)
15:37:26 <gundalow> imack: ah, excellent
15:37:27 <samccann> well welcome imack !
15:37:43 <imack> thanks :)
15:38:52 <gundalow> https://github.com/ansible/community/issues/389#issuecomment-458179675 last time we get to `* Integrating & cross linking parts of the User Guide`
15:39:13 <gundalow> imack: alongchamps anyting you'd like to add to the agenda, or ask before we begin?
15:39:48 <alongchamps> I was looking last week at some of the contributions material since I'm working on a module and had a particular behavior I wanted to check was OK
15:40:05 <gundalow> alongchamps: sure
15:40:15 <alongchamps> in this case, it would be when a module is going to configure something (this is for VMware ESXi in particular) should it replace what is there or append to it, or both?
15:40:49 <dag> o/
15:40:54 <alongchamps> the module I'm workin on in particular is for VMware host kernel modules, which take text options (e.g. ipv6=0) and I'm wondering if there's a best practice on if it should replace what's present or append
15:41:14 <samccann> #chair dag
15:41:14 <zodbot> Current chairs: alongchamps dag gundalow imack samccann
15:42:39 <dag> alongchamps: do you have a PR ready ?
15:43:15 <alongchamps> I don't have one yet; I'm testing it on my side for functionality and then I came up with this question
15:44:13 <dag> alongchamps: this question is not really related to documentation though
15:44:38 <alongchamps> ah, ok!
15:44:45 <samccann> dag: not directly, but alongchamps looked in our guide and couldn't find the answer
15:44:46 <dag> but let's discuss in private
15:45:08 <samccann> so seems like whatever the end result is - there should be a docs PR to add that detail to the dev. guide?
15:45:42 <dag> samccann: I understand, however I don't think we ever can answer all questions people will ever have (if we would, people wouldn't likely find the  necessary stuff ;-)
15:46:22 <alongchamps> is this most likely going to be a per-module or per-working group thing for how they behave, and then it's up to the contributors to document it properly?
15:46:35 <alongchamps> if so, that gives me some direction to go in
15:46:39 <samccann> but isn't whether to replace or append functionality important necessary stuff? or am I misinterpreting the request?
15:46:58 <dag> samccann: I don't think we have a good answer (not one that is acceptable)
15:47:08 <dag> do you want to discuss this here ?
15:47:37 <samccann> dag: not looking to make a decision here, but I think IF you come up with some general guidance, it seems something worth having in the dev guide
15:47:50 <samccann> but not if it's a case by case thing
15:47:58 <dag> it might
15:48:39 <gundalow> samccann: +1
15:48:42 <gundalow> "it depends"
15:48:57 <alongchamps> that's my favorite answer :)
15:49:12 * gundalow feels bad for using it though L(
15:49:35 <alongchamps> with the modules already in place though for lots of different things, I can see why it would be on a case-by-case basis
15:49:42 <dag> so the problem is that users may want to add, remove or replace items in a list to an object
15:50:02 <alongchamps> roughly, yes
15:50:18 <dag> and lots of infrastructure modules have separate modules for managing items in lists
15:50:56 <dag> generally if you manage the parent, it replaces the list, if you manage the list itself, you can add, remove and replace (state=pure)
15:51:16 <dag> some modules have an option "purge", but I don't think that is a good convention
15:52:27 <alongchamps> I think I will go with having it replace what's there on state: present and remove options when state: absent
15:52:38 <alongchamps> ty all for the discussion, this helps me
15:52:57 <dag> (we have modules that allow operations on child-objects etc, but those become very complex very quickly and doesn't give you proper feedback as to what has changed.happened)
15:53:22 <dag> alongchamps: it helps if we know what the module does, and what the user interface (arg_spec) is
15:53:53 <dag> but state=pure is what would replace what exists, and removes what is not provided
15:54:19 <alongchamps> this one configures vmware host kernel modules which have a module name then a space separated list of options. e.g. module: "tpcip4" and options: "ipv6=0"
15:54:20 <dag> (which is not exactly the same as remove everything, and then add)
15:54:27 <alongchamps> s/tpcip4/tcpip4
15:54:48 <dag> alongchamps: I think it makes more sense to manage the complete command line as a single object (i.e. not consider it a list)
15:54:48 <alongchamps> someone could run another module call that says module: "tcpip4" and options: "ipportScsiReserved=20"
15:55:04 <dag> right
15:55:12 <alongchamps> ESXi stores it internally that way, "kvpair1=option1 kvpair2=option2"
15:55:17 <alongchamps> just space separated
15:55:25 <dag> if that's the only thing the module does, yes, present/absent/pure would be best
15:55:34 <alongchamps> sounds good to me
15:55:52 <dag> and I would make it a dictionary (unless keys can be repeated, in that case it should be a list)
15:56:41 <dag> alongchamps: put me in (cc @dagwieers) in the PR and I will review and give feedback
15:56:53 <gundalow> alongchamps: hope that's helped :)
15:56:57 <gundalow> dag: Thanks :)
15:57:09 <alongchamps> it did, thanks dag and gundalow
15:57:35 <gundalow> ace
15:57:37 <gundalow> NEXT
15:57:49 <gundalow> #topic Integrating & cross linking parts of the User Guide
15:58:57 <dag> alongchamps: BTW don't we have a module doing this for Linux kernel modules ? (If we do, don't expect that module to have a good interface, it might be old ;-))
15:59:16 <gundalow> So this is partly discoverability & promotion
15:59:19 <alongchamps> this one is for VMware ESXi hosts - their hypervisor
15:59:27 <dag> https://docs.ansible.com/ansible/latest/modules/modprobe_module.html
15:59:27 <alongchamps> s/their/the
15:59:56 <dag> it's managing the module mostly (and optionally replaces any module options)
16:00:00 <alongchamps> so this would go into the VMware working group and based on my prior searches of the codebase/issues, there isn't one - I decided to use it to get my feet wet in writing modules
16:00:01 <gundalow> We have https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html though I'm wondering if we should mention some of those items in the Getting Started guides
16:00:04 <dag> so not the best example
16:00:29 <gundalow> Some people didn't know that `ansible-lint` was a thing
16:00:37 <alongchamps> i'll give both of those a look, thanks
16:00:54 <gundalow> likewise people didn't know you can make it easier to write Playbooks in your $EDITOR
16:00:59 <gundalow> What do people thing?
16:01:08 <samccann> gundalow: I'd like us to give a boost to ansible-lint for sure
16:01:40 * dag has some doubts on ansible-lint related to personal preferences and existing defaults
16:02:05 <samccann> for $EDITOR - maybe just a note to point over to that other tools etc section?  editor choice is ..ahem...a very opinionated selection for some folks
16:02:09 <dag> I am not certain we have shipped it in the past with the best defaults (and changing defaults is hard to impossible)
16:02:55 <gundalow> samccann: oh, sure, defo want to avoid editor wars. https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html covers a lot of editors
16:05:12 <samccann> gundalow: yeah that's why I'm thinking a strategically placed note 'somewhere' that says some editors have build in 'whatever' to help you write playbooks... and then a link to that existing section might be enough
16:05:36 <gundalow> Yup, that sounds good
16:10:26 <samccann> #agreed - add a note about editors making playbooks easier to write, with a link to https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html
16:10:53 <samccann> were we also agreed about `ansible-lint` ? sounds like dag had some  thoughts?
16:14:57 <samccann> hmm... things got quiet round here... anyone left here w/ an opinion on pointing users to `ansible-lint` to test playbooks etc?
16:16:34 <gundalow> samccann: yup, lets mention it
16:17:35 <samccann> #action samccann - add notes about editors and playbooks and ansible-lint
16:18:36 <samccann> #topic Open Floor
16:18:49 <samccann> Anyone have another docs topic they want to bring up?
16:19:57 <samccann> Friendly reminder we have 95 open docs PRs - so if you have some spare time, consider reviewing/commenting (and merging if you have those rights) - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
16:20:35 <samccann> or even going to the oldest in that list and adding a comment to ask the owner if they are making progress/still interested in the fix etc
16:23:09 <samccann> And for those new or looking for a place to jump in - this has some suggestions for docs (and other areas to contribute) - https://docs.ansible.com/ansible/latest/community/how_can_I_help.html#review-fix-and-maintain-the-documentation
16:24:46 <samccann> okay looks like we're winding down here.
16:24:59 <samccann> Thanks everyone for today's meeting!
16:25:07 <samccann> #endmeeting