15:57:06 <gundalow> #startmeeting Docs Sprint
15:57:06 <zodbot> Meeting started Mon Oct 10 15:57:06 2016 UTC.  The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:57:06 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:57:06 <zodbot> The meeting name has been set to 'docs_sprint'
15:57:10 <gundalow> #chair docschick
15:57:10 <zodbot> Current chairs: docschick gundalow
15:57:21 <gundalow> docschick: Everything is logged now :)
16:55:47 <docschick> hello :)
16:55:52 <docschick> awesome, thanks
16:56:08 <docschick> i can make the channel alright, but feel free to op others too
16:56:28 <docschick> we have no mic in the room, so i'll dial in with my phone and we can pass that around as a mic
16:57:50 <gundalow> docschick: ah, OK
16:58:32 * gundalow has an interest in the docs from an developer point of view
16:58:38 <gundalow> linuxdynasty: hey :)
16:59:12 <linuxdynasty> hello
16:59:15 <linuxdynasty> :)
17:07:12 <abadger1999> is there a bluejeans link or such for this meeting?
17:07:25 * abadger1999 not sure how he's going to multitask but will try.
17:07:46 <gundalow> #topic https://public.etherpad-mozilla.org/p/ansible-summit-october-2016-doc-sprint
17:07:49 <gundalow> abadger1999: in ^
17:07:58 <gundalow> Starts in 30 minutes
17:11:22 <docschick> you can dial in now, though. we're starting to gather in the room farthest away from the rest of the conference ;)
17:11:23 <docschick> https://bluejeans.com/563045112
17:23:13 * abadger1999 dialed in via blue jeans on phone.  Mya switch over to tablet once he gets blue jeans installed there.
17:28:19 <gundalow> Meeting has started, see topic for BlueJeans details
17:29:54 <abadger1999> docschick: Can you turn the camera to the speaker for intros
17:30:07 <abadger1999> Thanks!
17:34:43 <abadger1999> organization -- google is the only way for me to find things.  When I add information, I often duplicate it or put it in the wrong section (or it's already duplicated).
17:37:00 <abadger1999> ah -- no complaints about swift; it's mostly search vs browse that I'm talking about.
17:37:57 <zodbot> abadger1999: Error: Can't start another meeting, one is in progress.
17:38:03 <abadger1999> Just checking :-)
17:38:10 <gundalow> #chair abadger1999
17:38:10 <zodbot> Current chairs: abadger1999 docschick gundalow
17:38:31 <docschick> can everyone still hear? one report of lost audio
17:38:35 <misc> I can
17:38:41 <gundalow> loud and clear :)
17:38:41 <abadger1999> I can hear.
17:38:58 <docschick> thanks!
17:39:13 <abadger1999> tima mentioning that the parameters in the table at the top is not the best.
17:39:31 <abadger1999> Required vs optional is a problem that both tima nad mperz have seen.
17:39:50 <abadger1999> table within a table has shown up somewhere.
17:40:03 <misc> yeah, for return code
17:42:42 <gundalow> #chair dharmabumstead
17:42:42 <zodbot> Current chairs: abadger1999 dharmabumstead docschick gundalow
17:42:50 <docschick> https://public.etherpad-mozilla.org/p/ansible-summit-october-2016-doc-sprint -- in case it's needed
17:42:56 <docschick> or see topic :)
17:44:07 <abadger1999> dharmabumstead: the (partial) story so far: http://paste.fedoraproject.org/447792/12143214/
17:53:30 <abadger1999> Someone asked whether we can have a QA doc -- that tells contributors and bleeding edge users how to test release cnadidates.
17:53:59 <bcoca> wouldnt that overlap with developer docs on how to test their modules?
17:54:09 <bcoca> or features to core
17:54:15 <abadger1999> gundalow says that we could modify the installing page for that.
17:54:35 <bcoca> i would leave installing page simple, link 'develoeprs, qa' page from there
18:03:02 <abadger1999> Question about whether to pull the docs into a separate repo.
18:03:16 <abadger1999> (except for modules)
18:03:29 * abadger1999 sees pros and cons
18:03:50 <abadger1999> gundalow saying that one danger is that versions are no longer automatically synced.
18:05:26 <abadger1999> misc says it means that we can't verify that the docs are updated when the code is updated.
18:06:42 <misc> we have separate repo for glsuter, and so we can't refuse PR because they do add a feature that is not documented (or rather, that's not as seamless as it would with a merged repo)
18:07:12 <bcoca> one thing i wanted to add is autogenerate code for all plugins like we do in modules, so lookup, callback, filter, etc
18:07:33 <abadger1999> dharmabumstead brings up that currently the jenkins doc build tests the code and therefore docs build can fail due to code changes.
18:07:48 <bcoca> as for rest of docs, we dont guarantee that they are in sync, but much easier to keep in sync vs having 2 PRs to 2 diff repos (core/extras anyone?)
18:08:24 <abadger1999> Sam brings up that module docs being integrated in the modules is a more annoying thing (mainly... would be good to have an easy way to test the module docs)
18:08:32 <bcoca> not sure why doc builds test code, aside from ansible-doc nothing else should care
18:08:46 <bcoca> ansible-doc module ?
18:09:26 <abadger1999> yeah... I think that might be a problem with the jenkins job configuration rather than what's in the repositories.
18:09:27 <bcoca> anisble-doc modulename <= should test 'correct doc structure'
18:10:03 <gundalow> .win 24
18:12:24 <abadger1999> ah Sam is actually supertom (just the way that bluejeans is hearing things)
18:12:46 <gundalow> "Sam" is everyone, she is passing her phone around
18:13:21 <gundalow> supertom: https://github.com/sivel/ansible-testing/
18:13:47 <gundalow> supertom: "ansible-validate-modules /path/to/ansible-modules-extras
18:14:01 <supertom> thanks @gundalow
18:14:49 <gundalow> supertom: "ansible-validate-modules /path/to/ansible-modules-extras" is what Shippable runs when you raise a PR
18:14:57 <abadger1999> dharmabumstead brings up that we could have separate standards for how git merges are handled in a docs repo vs a core repo
18:15:25 <abadger1999> So that if someone makes a merge commit that pulls in the past 5 hundred commits, that oculd be legal i nthe docs repo.
18:15:39 <bcoca> i would say that is more a problem than a feature
18:16:11 <abadger1999> tima brings up categorization of docs pull requests and issues.
18:16:56 <bcoca> lets make pro/cons list, im remiss of spitting the repo again right before we unite it
18:19:29 <abadger1999> dharmabumstead brings in the question of editorial control over docs.
18:20:01 <bcoca> i thought his group had that, with help from core for 'correctness'
18:21:14 <abadger1999> bcoca: I think we haven't really said the policy and told all committers is the problem
18:21:39 <supertom> maybe a docs directory, if not a repo?  Something that keeps it separate so it could be merged quicker, or flagged more easily for others?
18:21:43 <bcoca> ^ goes back to my 'we need a list to commiters and notify them when we update the rules'
18:21:54 <bcoca> we have docs directory already
18:22:06 <bcoca> docsite/rst <= to be specific
18:22:16 <supertom> I was thinking per-module
18:22:28 <supertom> but I agree, this is the "how" without defining the "what"
18:22:30 <misc> we have a policy on docs ?
18:22:48 <abadger1999> note:  The pieces that dharmabumstead was talking about do not affect the module docs.
18:23:03 <bcoca> abadger1999: i have reverted doc commits when they were 'wrong', dharmabumstead you shoujld be able to do same
18:23:12 <abadger1999> which is problematic :-(
18:23:22 <gundalow> misc: If you are talking about my point I was mainly refering to Module documentation
18:23:27 <bcoca> its 'worst case' but probalby the start of conversation
18:23:30 <abadger1999> (module docs are more problematic than the docsite/rst docs)
18:23:31 <dharmabumstead> one of the problems having a separate docs repo would solve would be that you *wouldn’t* have someone merging the past 500 commits because the volume for doc contribs would be *way* lower.
18:23:35 <abadger1999> not the revert :-)
18:23:58 <bcoca> dharmabumstead: we have that problem with random PRs not specifically docs
18:23:59 <dharmabumstead> as far as editorial ‘control'...
18:24:22 <abadger1999> Yeah, it's an issue with git having ways to do things that lead to that happening.
18:24:33 <misc> we have rebase and merge, no ?
18:24:35 <abadger1999> not necessarily the volume of commits
18:24:39 <bcoca> and squash
18:24:49 <abadger1999> misc: yeah... but not everyone understands when and how to use rebase.
18:24:55 <dharmabumstead> there’s no easy way for someone to look at the ansible repo now and just pick out the doc commits.
18:24:59 <abadger1999> which is how that particular thing came about.
18:25:02 <bcoca> docs tend to have much lesser frequency of commits, also we tend to merge them faster as they have little repercussions to the code
18:25:08 <misc> abadger1999: true, so maybe we should replace that with a bot that do the right thing ?
18:25:12 <abadger1999> dharmabumstead: current commits or past commits?
18:25:14 <abadger1999> err
18:25:18 <dharmabumstead> which i think would make it all the better for docs to have their own repo
18:25:19 <bcoca> dharmabumstead: actually, outside of modules, its pretty easy, just filter by docsite/
18:25:19 <abadger1999> PRs or past commits?
18:25:29 <dharmabumstead> either or
18:25:31 <abadger1999> <nod> what bcoca said for psat commits
18:25:33 <bcoca> PRs are labeled
18:25:41 <abadger1999> PRs jctanner's bot can do it.
18:25:44 <bcoca> doc_pull_request
18:25:53 <bcoca> ^ even if manual, we've been doing it
18:26:24 <gundalow> Discussion about what should be in a style guide
18:26:32 <gundalow> k=v or k:v
18:26:35 <dharmabumstead> for modules
18:26:40 <dharmabumstead> (style guide)
18:26:44 <gundalow> yup, for modules
18:26:46 <abadger1999> we should make sure that's a feature he has implemented
18:26:46 * misc is team :
18:26:50 <gundalow> misc: +1
18:27:02 <abadger1999> k: v is best practice.  should be in the style guide.
18:27:06 <bcoca> im ok with either k=v or k: v, i think both are useful
18:27:15 <abadger1999> k=v should be used in just a few places.
18:27:35 <gundalow> k=v for ad-hoc, where else does it make sense?
18:27:38 <abadger1999> where the prime use case is adhoc (/usr/bin/ansible) instead of playbook.
18:27:42 <abadger1999> yep.
18:27:48 <bcoca> abadger1999: i would say, k: v avoids some corner cases, i would not categorically say k: v is 'best practice'
18:28:01 <supertom> @gundalow, BTW, works great.  Broke a module to see it work.  Thanks!
18:28:23 <misc> k: v force people to make each argument on 1 line, and so permit to show directly in diff what got changed
18:28:26 <gundalow> supertom: cool, feel free to ping me directly if you have issues
18:28:31 <bcoca> k=v makes sense for readability, when your horizontal space is more plentiful than your vertical
18:29:17 <bcoca> i think k: v is less problematic from the execution side, but k=v is something that most people are more comfortable with
18:29:47 <abadger1999> there's tradeoffs even then.  density is not always better than things scrolling off the edge.
18:29:59 <abadger1999> (even then = vertical vs horizontal space)
18:30:03 <bcoca> agreed, but let users make the tradeoff
18:30:46 <abadger1999> bcoca: right... we're not removing the feature... we're not even documenting it as best practice for users... it's the style guide for our docs.
18:31:10 <abadger1999> make have the docs say k: v
18:31:13 <bcoca> aside from lininfile/blockinfile/replace modules, rest should be fine either way
18:31:29 <bcoca> docs ONLY using k: v makes it seem k=v is not legal
18:31:57 <abadger1999> which too me is fine.
18:32:08 <abadger1999> k=v exists if they want to use it.
18:32:19 <bcoca> But not going to press on it, if that is what the majority wants as 'doc format', fine, but k=v does make it easier for users to pick up ansible, even if it can cause issues later on
18:32:20 <misc> well, mixing might make things be more complicated to users, who will wonder what to use
18:32:43 <misc> "ie, why is is k:v for this module and k=v for this modules"
18:33:01 <misc> but indeed, you also need to be more confortable with yaml to get it
18:33:05 <bcoca> misc: depends, some modules even have both in examples, what should be clear is in 'introduciton docs' taht both formats are available
18:33:10 <bcoca> with examples
18:33:29 <gundalow> having both in examples must be *reall* confusing for new users
18:33:30 <abadger1999> <nod> agreed that intro docs should show both.
18:33:57 <bcoca> i have not heard a user complain yet about k: v and k=v format making it unclear what they should use
18:34:06 <bcoca> ^ and i hear them complain a lot about many other things
18:34:37 <bcoca> again, i dont care too much about this, i think there are plenty of much more important issues we need to deal with docsland
18:34:42 * gundalow has had someone ask if some modules work in different ways as they sayk=v and k:v in different modules
18:34:46 <bcoca> and this can go to botom of list
18:34:48 <gundalow> bcoca: That's a good point
18:35:11 <misc> we can discuss of the mode style, 0755 vs "u+rw,g-wx,o-rwx" :)
18:35:35 <bcoca> we need to support both
18:35:37 <gundalow> misc: :)
18:35:55 <bcoca> even u:user:r-x
18:36:08 <bcoca> ^ solaris chmod uses acl type format
18:36:34 <misc> my annoyance is that I did convert lots of stuff from salt
18:36:34 <abadger1999> ansible-examples needs an owner.
18:36:43 <bcoca> we have ansible-examples?
18:36:45 <misc> and I kinda used 755 instead of 0755 a lot
18:36:52 <gundalow> mperz and tima to own ansible-examples
18:36:55 <abadger1999> mperz and tima volunteering to make sure it is up to date with best practices
18:37:07 <abadger1999> bcoca: the github repo
18:37:15 <bcoca> ah, the sample plays/roles
18:37:19 <gundalow> yup
18:37:22 <bcoca> thoguht it was new cli
18:37:27 <abadger1999> https://github.com/ansible/ansible-examples
18:37:27 <gundalow> heeh
18:38:08 <abadger1999> bcoca: New challenge?  ansible-example role-to-setup-nginx-server ;-)
18:38:24 <bcoca> ^ dont we have 4300 of those in galaxy?
18:38:30 <gundalow> probs need another galaxy role for nginx
18:44:22 <gundalow> jtanner: see topic for etherpad link
18:45:23 <jtanner> so did we decide to move docs to mediawiki yet? :troll:
18:45:49 <dharmabumstead> might as well.
18:49:57 <gundalow> Example docs fragments for modules https://github.com/ansible/ansible/blob/devel/lib/ansible/utils/module_docs_fragments/dellos10.py
18:51:01 <bcoca> ^ on thing i've been wanting for along time, move doc_fragments to lib/ansible/plugins
18:51:18 <bcoca> another thing on my list, make them "overridable"
18:51:35 <bcoca> optiona/version_added: 1.3, but for this module its 2.3
18:51:48 <abadger1999> https://github.com/ansible/ansible/blob/devel/lib/ansible/module_utils/ec2.py#L122
18:52:52 <gundalow> bcoca: what does overridable mean in this context?
18:53:23 <abadger1999> Thanks for organizing it docschick!
18:53:28 <bcoca> as i said, doc fragment states version 1.3, but module x implemented it in 2.3
18:53:39 <docschick> glad to be here for this!
18:53:50 <gundalow> I'll leave the meeting running in here for a little bit longer so we capture anything else that's said
18:53:52 <abadger1999> and thanks to dharmabumstead for thowing all these ideas and plans out here!
18:53:53 <bcoca> ^ dont think we should allow/override anything other than version
18:53:57 <abadger1999> for discussion
18:54:08 <gundalow> Thank's y'all
18:54:39 <dharmabumstead> “red warrior needs food…badly”
18:55:08 <dharmabumstead> (nobody here remembers playing gauntlet)
18:55:34 <bcoca> <= is nobody
18:55:35 <gundalow> #endmeeting