15:31:22 <acozine> #startmeeting Docs Working Group
15:31:22 <zodbot> Meeting started Tue Mar 12 15:31:22 2019 UTC.
15:31:22 <zodbot> This meeting is logged and archived in a public location.
15:31:22 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:31:22 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:31:22 <zodbot> The meeting name has been set to 'docs_working_group'
15:31:44 <acozine> #chairs gundalow samccann bcoca felixfontein Xaroth
15:31:52 <acozine> er
15:32:02 <acozine> #chair gundalow samccann bcoca felixfontein Xaroth
15:32:02 <zodbot> Current chairs: Xaroth acozine bcoca felixfontein gundalow samccann
15:32:33 <acozine> who else is around?
15:32:46 <acozine> alongchamps you here?
15:33:01 <alongchamps> kind of, actually in more VMware meetings that I should pay attention to
15:33:03 * samccann waves
15:33:38 <acozine> competing meetings!
15:33:47 <acozine> okay, I won't make you a chair then
15:34:17 <alongchamps> that works
15:34:21 <samccann> I'd like to spend today's meeting as a lamppost please
15:34:35 <acozine> samccann: shedding light? I love it
15:34:43 <acozine> #topic Discussion of namespacing in docs examples, including https://github.com/ansible/ansible/pull/53595/files
15:34:52 <acozine> looks like that's been under discussion already today
15:35:00 <Xaroth> samccann: being an inanimate object that people run into when they don't pay attention?
15:35:06 <felixfontein> dag: are you around?
15:35:52 <acozine> hm, not immediately at least . . .
15:36:03 <samccann> Xaroth: I have delusions about being illuminating!  😉
15:36:09 <Xaroth> :D
15:36:20 <Xaroth> I'm not really a fan of that PR
15:36:29 <Xaroth> it only adds complexity in an already rather complex area
15:36:30 <acozine> ah, interesting
15:37:22 <acozine> the discussion earlier tended toward "consistency is our main goal", and using the ansible_facts namespace with the [field] notation would be consistent
15:37:30 <acozine> Xaroth: what are your thoughts?
15:37:32 <bcoca> i don't think it adds complexity, it does go for a longer notation, but it is also less problematic
15:38:30 <Xaroth> To me, ansible_os_distribution  is a lot easier to grasp, than ansible_facts['os_distribution']
15:39:09 <felixfontein> replacing ansible_xxx with ansible_facts.xxx is I think OK, especially since we have recommended that (already in Ansible 2.5). but using the array notation is a bit too much IMO.
15:39:27 <samccann> I'm on the flip side of that one Xaroth - I understand 'ansible_facts' exists and has loads of 'stuff' in it.  So I inherently know what ansible_facts['os_distribution'] is coming from.  Not so much on the other approach
15:39:58 <acozine> agreed that it's easier to grasp - does training people with `ansible_facts['os_distribution']` make it easier for them to understand using their JSON output when they start getting more complicated stuff?
15:40:42 <samccann> as for dot vs array - bcoca convinced me in the earlier discussion that the array is 'safer' to use.  So I'm inclined to say that should be what's preferred in our doc examples.  People can do what they like in their own playbooks etc
15:40:54 <acozine> it feels like having an easy-to-grasp notation and names is fine if the user never interacts with anything beyond those
15:41:25 <Xaroth> It's funny though, samccann, because Jinja/Django explicitly made the dot notation variant, because it was easier to use.
15:41:50 <bcoca> Xaroth: its not easier when it lays traps for the user
15:41:53 <acozine> Xaroth: are there examples where the array notation is required?
15:41:55 <felixfontein> it IS easier to use, but also makes it easier to screw up, when you use the wrong names...
15:42:06 <Xaroth> acozine: dict_var.keys
15:42:07 <samccann> yeah I have soo very very limited experience with Jinja (or python for that matter). So I may not be the target audience
15:42:08 <felixfontein> acozine: array['something with - and spaces']
15:42:16 <bcoca> its easier for programmers cause they know dot notation already, maybe for users since its less characters, but .. pitfalls ...
15:42:25 <felixfontein> and some_dictionary.items
15:42:39 <bcoca> Xaroth: that is examle that breaks dot notation
15:42:48 <bcoca> we are talking about dot notation for 'dictionary access'
15:42:59 <Xaroth> mhm, hence answering acozine, that in those cases array notation is required.
15:43:02 <bcoca> dict.keys  will always be used that way IF going for the method
15:43:04 <acozine> so all cases will work with `thing[sub-thing]` but only simple cases work with `thing.subthing`?
15:43:04 <felixfontein> people tried doing stuff like  groups.my-group  and  result.items  before
15:43:08 <samccann> so if programmers know the doc notation, do they 'not' know the array notation? or is it just longer to type/look at but they do know exactly what it's doing?
15:43:26 <Xaroth> acozine, the dot notation does a getattr() on the object, to find it
15:43:30 <bcoca> 'longer to type'
15:43:31 <felixfontein> samccann: programmers are usually lazy, so they prefer the shorter notation
15:43:35 <Xaroth> so if there's a method with that name, it will return that
15:43:44 <Xaroth> if it cannot find an attr, it tries to do getitem()
15:43:46 <acozine> okay, and when there isn't . . .
15:43:49 <bcoca> Xaroth: posted all this in ticket
15:43:57 <Xaroth> which traverses dicts to subelements
15:44:05 <samccann> well, programmers can style type what they please, right? We're talking about what WE put in documentation?
15:44:18 <acozine> samccann: yeah, I'm thinking along those lines
15:44:27 <Xaroth> {{ a.x }} does (in python) try: return a.x except AttributeError: return a['x']
15:44:36 <samccann> So that WE help prevent mistakes from those less savy about the dot pitfalls if they copy our approach
15:44:54 <Xaroth> It's not just about helping prevent mistakes, samccann
15:45:13 <samccann> Though it would also mean we'd have to reject/ask for changes from any programmer who puts a doc PR with dot notation?
15:45:16 <bcoca> most non progammers wont understand the difference
15:45:25 <Xaroth> one of the main reasons we (internally) went for Ansible over Salt/others, is that it was more readable.
15:45:42 <bcoca> Xaroth: we are not preventing the use of dot notation, no one is saying that
15:45:58 <samccann> foo.bar vs foo['bar'] from this nonprogrammer is about the same
15:46:21 <Xaroth> yes, but keep in mind the target audience of people who have not yet decided whether or not to go with answible
15:47:20 <samccann> this is where I get confused Xaroth  - is our biggest target audience python (or programmers in general) or IT people who need to pick up enough programming skills to write Ansible playbooks?
15:47:48 <samccann> or maybe that was your point - the nonprogrammer would find the array notation harder to grasp than the dot notation?
15:48:00 <Xaroth> ^
15:48:15 <bcoca> all of the above
15:48:30 <Xaroth> Ansible being aimed at devops, means you have to deal with people who don't even know what a shell is, to people who can write python blindfolded.
15:48:44 <samccann> perhaps what we should do then, is find the gnarliest example and convert to array with full namespace and see how hideous (or not) it is?
15:49:18 <acozine> can we put together a page on "dot notation vs array notation" that outlines the rules on when you can and when you cannot use the dot notation?
15:49:30 <acozine> then link to it from just about everywhere?
15:50:06 <Xaroth> samccann: like {{ ansible_device_links.ids.sr0 }} vs {{ ansible_facts['device_links']['ids']['sr0'] }}  ?
15:50:13 <felixfontein> maybe we should have two versions of all documentation. if anyone is too bored ;)
15:50:23 <samccann> AHAHAHA
15:50:33 <samccann> and thanks Xaroth that example helps
15:50:41 <acozine> heh, sure . . . with a toggle in the UI so you can select not only the version of the docs but the style of your examples
15:50:55 <samccann> I still find the ansible_facts array easier, but I've already drunk that coolaid
15:51:08 <Xaroth> bcoca: ansible_facts, does that contain vars/defaults from roles?
15:51:17 <bcoca> no, it contains ansible_facts
15:51:23 <Xaroth> hm
15:51:30 <felixfontein> I find the array syntax annoying in long expressions; for short things both are fine to me
15:51:39 <samccann> Seems like the decision boils down to - do we want mor readable/scannable docs (aka dot notation with or w/o namespace) or do we want docs that help prevent mistakes (array)
15:51:41 <Xaroth> felixfontein: same
15:51:58 <bcoca> ansible_distribution CAN be a fact or can be a variable, while anything under ansible_facts.  should be a fact, unless you redefine the whoel ansible_facts
15:52:14 <Xaroth> So we also have to explain people what the difference is between vars and facts then as well
15:52:29 <bcoca> facts ARE vars ... we have 13 types of vars ...
15:52:30 <acozine> that's probably good information to have out there anyway
15:52:38 <bcoca> or 16 .. i forget ...
15:52:51 <bcoca> not all vars are 'facts' though
15:53:06 <bcoca> facts are ONE type of vars, like role_defaults  or extra vars
15:53:19 <bcoca> each type has diff precedence, scope and properties
15:53:59 <felixfontein> i.e. pure hell
15:54:07 <bcoca> https://github.com/ansible/proposals/issues/127 <= why i proposed redesign
15:54:45 <bcoca> and set_Fact does NOT set facts ... except now it does if cacheable=true, but not really since that makes it actually set 2 vars, 1 of them a fact ...
15:55:16 * bcoca is in a mobious strip inside a rabbit hole at the center of a black hole that is eating itself
15:55:26 <Xaroth> I like the access via certain identifiers for certain type of vars.
15:55:29 <samccann> muncha munch
15:55:32 <Xaroth> but that's just me.
15:55:37 <acozine> so it sounds like we have two main goals: 1. reassure new users by offering the simpler dot notation, at least in intro docs, and 2. help all users understand the limits of the dot notation, with some examples in the longer notation
15:55:44 <bcoca> hostvasr['anyone?']
15:55:57 <Xaroth> I so dislike having to use hostvars
15:56:03 <acozine> and goal 2 involves a deeper dive into the question of vars and facts
15:56:46 <bcoca> https://docs.ansible.com/ansible/latest/reference_appendices/faq.html?#ansible-supports-dot-notation-and-array-notation-for-variables-which-notation-should-i-use
15:56:51 <bcoca> we already explain
15:56:53 <acozine> bcoca: is proposal 127 on the road map?
15:57:32 <bcoca> acozine: only in the one in my head
15:57:40 <acozine> bcoca: thanks for the pointer to that FAQ - it's a good start, but if I were a new user, I might not even know to look at that entry
15:57:49 <acozine> heh
15:57:58 <Xaroth> I had been working with Ansible for months before I even realized there was a FAQ page :P
15:58:03 <bcoca> problem with vars system .. it woudl be incompatible
15:58:15 <acozine> incompatible with what?
15:58:20 <bcoca> existing playbooks
15:58:30 <acozine> ah, backwards incompatible
15:58:36 <acozine> Ansible 3.0, anyone?
15:58:37 <Xaroth> so it would be something for Ansible 3.0 ?
15:58:41 <acozine> jinx
15:58:42 <Xaroth> ... *eyes acozine*
15:58:43 <bcoca> current system is insane and making any new system backwards compatible ... removes the purpose of creating new system
15:58:49 <bcoca> yes, mythical 3.0
15:59:03 <acozine> so looking back at our topic
15:59:34 <acozine> I think we are divided about the current PR, and some additional work/research is in order
16:00:42 <acozine> #actionitem create proposal for more complete description of namespace and notation use, with recommendations about where/when to use dot notation in examples
16:01:05 <acozine> anything else to add to that topic?
16:01:31 <acozine> hearing none . . .
16:01:35 <acozine> #topic Review of ansible/ansible#53569, which addresses an idea that came out of an earlier DaWG meeting.
16:02:03 <acozine> the branch is currently published at http://docs.testing.ansible.com/ansible/latest/scenario_guides/integration_guides.html
16:02:24 <acozine> earlier chat supported samccann's idea of putting `Ansible` back into the titles
16:02:29 <acozine> so I'll do that
16:02:42 <acozine> other ideas, suggestions, concerns, etc.?
16:03:01 <samccann> +1  I think it's a great improvement
16:03:06 <acozine> I'm happy with the TOC changes, and I don't think we'll need too many redirects
16:03:25 <acozine> anybody here currently maintain an Integration (formerly Scenario) Guide?
16:04:05 <samccann> my one question - 'Integrating ansible with other tools' section - does that convey what they are?  (products/platforms/?)
16:04:17 <acozine> ah, good question
16:04:56 <acozine> I wanted something short, so the full title shows up without the left nav eating too much screen
16:05:19 <acozine> and I thought just `Integrating Ansible` was a bit too cryptic
16:05:39 <acozine> sounds like the Deep South in 1970
16:05:49 <samccann> yeah. `Integrating Ansible with other Platforms` ?
16:06:01 <samccann> maybe tools is better
16:06:06 <acozine> is ACI a platform?
16:06:15 <samccann> vagrant is definitely a tool
16:06:20 <acozine> maybe there's a better generic term
16:06:22 <samccann> but most are products or platforms imo
16:06:24 <bcoca> fyi, new vmware guide is in it's own section, while it used to be in general one in 2.5
16:06:30 <bcoca> ^ noticed last week
16:06:32 <alongchamps> ACI is a Cisco platform for their switches
16:06:33 <acozine> bcoca: that's by design
16:06:45 <acozine> we shouldn't be privileging vmware IMO
16:07:53 <acozine> bcoca: VMware used to have its own section of the main TOC
16:08:04 <alongchamps> did we go over some of this last week in the talks about restructuring the docs? since VMware is definitely a platform and there are a lot of other cloud modules
16:08:24 <acozine> we talked about this either last week or the week before
16:08:43 <samccann> alongchamps yes and I think we decided to tuck vmware in with all the rest, under the integrations guides section
16:08:53 <alongchamps> that's what I remember
16:09:07 <acozine> we also moved one bit of content out - the CD and Rolling Upgrades page
16:09:20 <acozine> and by "we" there, I mean me/this PR
16:09:22 <bcoca> acozine: it just made it harder for me to find, also the 2.5 version is first on google results
16:09:39 <acozine> bcoca: yeah, findability is a concern
16:10:42 <Xaroth> I have to step out, I might be back in a bit, depends on the length of this meeting
16:10:48 <acozine> but giving AWS, Vagrant, Infoblox, Docker, etc. each its own section of the left nav would eat the TOC in time
16:11:06 <acozine> Xaroth: thanks for participating - see you later!
16:11:10 <Xaroth> o7
16:11:33 <bcoca> i would suggest, 'guides' section and giving network/cloud/virtualization their own 'sub sections'
16:11:58 <bcoca> you just dont see the vmware and networking now, unles syou know they are 'down there'
16:12:14 <acozine> networking is still its own section
16:12:23 <acozine> but yeah, it's harder to see the vmware guide
16:12:36 <alongchamps> do we want to make the docs mimic the file structure under https://github.com/ansible/ansible/tree/devel/lib/ansible/modules ?
16:12:59 <acozine> alongchamps: meaning, the rst docs?
16:13:12 <acozine> or the module docs?
16:13:23 <alongchamps> oh, I was thinking module docs
16:13:35 <alongchamps> a the github tree has the major categories like networking, cloud, etc.
16:13:37 <acozine> gotcha
16:13:48 <acozine> yeah, we do some of that with the module index pages
16:13:55 <acozine> but this PR only touches the rst docs
16:14:14 <acozine> things like http://docs.testing.ansible.com/ansible/latest/scenario_guides/guide_docker.html
16:14:44 <acozine> and http://docs.testing.ansible.com/ansible/latest/scenario_guides/guide_infoblox.html
16:14:58 <acozine> and now, http://docs.testing.ansible.com/ansible/latest/scenario_guides/guide_vmware.html
16:15:48 <acozine> bcoca: do you think subsections for Network Guides, Cloud Guides, and Virtualization Guides would improve findability?
16:16:05 <acozine> it will add another layer between the top-level TOC and the titles
16:16:18 <bcoca> under guides, yes, cause it would show there are diff types, right now you only see the 'cloud' guides since they are on top
16:16:31 <bcoca> i think that layer is find as long as it is meaningful
16:16:54 <acozine> ah, by "on top" you mean the first few in the list are cloud guides?
16:17:23 <acozine> that's a good idea, I'll test that out
16:17:35 <acozine> and republish to see if it looks better
16:17:57 <acozine> anything else on the Scenario/Integration guides PR?
16:18:26 <acozine> alongchamps: the index pages I was talking about are the ones linked here: http://docs.testing.ansible.com/ansible/latest/modules/modules_by_category.html
16:18:37 <acozine> oh, I'm posting lots of links to the docs testingsite
16:18:42 <acozine> those will not be stable
16:19:37 <acozine> #info don't use any links to docs.testing.ansible.com for anything other than testing!
16:20:04 <acozine> okay, next topic
16:20:27 <acozine> #topic docs version switching
16:20:33 <acozine> ansible/ansible#53317 and related issues, including ansible/ansible#45651, ansible/ansible#41782, ansible/ansible#37049, ansible/ansible#28553, and for context and reference, ansible/proposals#60.
16:21:00 <acozine> the current open PR is https://github.com/ansible/ansible/pull/53317
16:21:37 <acozine> I see dag and samccann both commented on the PR
16:22:11 <acozine> we've only got ten minutes, so unless everyone piles on with "Merge That, Merge It Now", we'll carry this discussion over to next week
16:22:28 <acozine> #chair
16:22:28 <zodbot> Current chairs: Xaroth acozine bcoca felixfontein gundalow samccann
16:22:31 <samccann> On the one hand, I 'expected' the ability to switch versions to be at the top of that page.  But now that I look at more 'readthedocs' sites, they are all at the bottom
16:23:03 <samccann> but the biggest issue is getting the url to stay the same when I switch versions.  Right now, if I'm in the middle of a guide and select a different version, it goes to the top of the doctree in that new version
16:23:33 <acozine> hm, that's not great UX
16:23:57 <acozine> it should only do that if the page doesn't exist in the prior version
16:24:08 <acozine> for example, the become plugins page
16:24:23 <acozine> doesn't exist in 2.7 because the functionality didn't exist
16:24:30 <acozine> but most pages carry over
16:24:32 <samccann> yeah so that's a definite fix.  The top vs the bottom (where it all shows up) I'm less concerned with
16:25:10 <acozine> wow, this is a much quieter topic than I expected!
16:25:43 <gundalow> Do we need per-page links? Or is it OK to drop user at `/` when they swap versions?
16:26:18 <acozine> gundalow: that's what samccann was saying - it would be better to try to get the same page with the other version, and if it's a 404, redirect to `/`
16:26:24 <samccann> the examples for other sphinx docs all keep  the same page when they swap, so it should be 'doable'
16:26:44 <alongchamps> as an end user, I would want to go to the page I'm viewing in the new version if available
16:26:46 <samccann> unless I'm missing something obvious
16:27:10 <samccann> so I think we give the PR owner some time/breathing room to experiment with the existing comments on the PR
16:27:33 <gundalow> Would you ever want to swap back and forth between versions?
16:27:33 <acozine> I'm not sure how this interacts with server-side redirects - if we do move the vmware guide, how does that play out when the user switches from 2.7 to 2.8?
16:28:08 <acozine> I suspect the most common use case is "oh, wait, this is an old version???"
16:28:18 <alongchamps> +1
16:28:20 <acozine> so swapping forth, but not back?
16:28:26 <acozine> as ot were
16:28:31 <alongchamps> yeah
16:28:34 <acozine> s/ot/it/g
16:28:40 <samccann> I've gone back
16:28:46 <alongchamps> e.g. I search for a vmware module, land on version 2.4 but I really want 2.7
16:28:49 <samccann> but that might just be because of backporting fun
16:28:55 <alongchamps> or I'm coding something and need to be on devel
16:29:01 <samccann> I think alongchamps point is the more valid one
16:29:02 * acozine hears the harp sound from flashback scenes in old movies
16:29:37 <samccann> but in general, not sure what happens (other than 404) if you change versions and something is no longer there.
16:29:51 <acozine> good, we have a couple of testable use cases
16:29:53 * alongchamps going back to my desk
16:29:53 * gundalow just wants to make sure we aren't making something overly complex
16:29:55 <samccann> (or wasn't there in an older version).  Going forward 'should' trigger the redirect. going back is just 404 hell
16:30:53 <acozine> when we put this functionality in, we should really include an "OLD VERSION" banner, as we've discussed in the past
16:31:06 <acozine> so people know when they're not looking at the latest
16:31:30 <gundalow> Can we do banner first (independently)?
16:31:52 <acozine> yes, we can
16:32:27 <acozine> I don't think I'm the right person to try coding that, but we could definitely do a banner first
16:33:16 <acozine> it could be part of the release checklist - when the new version gets marked `latest`, the version before gets the `Old Version` banner
16:33:37 <acozine> and the version that is no longer supported could get an even stronger banner
16:34:19 <acozine> oops, we're over time
16:34:25 <gundalow> Oh, nice idea on non-supported
16:35:19 <acozine> okay, for next week, I'll have the results of that version-switch PR published to the testing site and we can take the next steps with it
16:35:20 <gundalow> Nothing else from me
16:35:26 <gundalow> Woot
16:35:31 <acozine> Thanks everybody!
16:35:42 <samccann> \o/
16:35:48 <acozine> #endmeeting