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