15:00:50 <acozine> #startmeeting Docs Working Group aka DaWGs
15:00:50 <zodbot> Meeting started Tue May  7 15:00:50 2019 UTC.
15:00:50 <zodbot> This meeting is logged and archived in a public location.
15:00:50 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:00:50 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:00:50 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:01:00 <acozine> #chair samccann gundalow
15:01:00 <zodbot> Current chairs: acozine gundalow samccann
15:01:07 <acozine> who else is around?
15:01:42 * samccann waves
15:02:23 <acozine> samccann: hi!
15:03:06 * alongchamps waves
15:03:24 <acozine> alongchamps bizonk dag decentral1se felixfontein Pilou shaps zoredache andersson007_ you runnin' with the DaWGs today?
15:03:29 <acozine> #chair alongchamps
15:03:29 <zodbot> Current chairs: acozine alongchamps gundalow samccann
15:03:46 <acozine> alongchamps: timezone-appropriate greetings!
15:04:09 <acozine> while we're getting warmed up, I would like to mention a milestone
15:04:42 <acozine> we are down to 60 open PRs labelled `docs`: https://github.com/ansible/ansible/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3Adocs
15:05:22 <samccann> woot!!
15:05:38 <samccann> that's some amazing progress!!
15:06:04 <acozine> this is a testament to the contributions of this community - thanks for the reviews, thanks for making PRs that are easy to assess, and thanks above all for working to make the Ansible docs better
15:06:12 <acozine> together we can do wonders
15:06:15 <alongchamps> woohoo
15:06:52 <felixfontein> hey!
15:06:55 <felixfontein> I'm here :)
15:07:07 <acozine> #chair felixfontein
15:07:07 <zodbot> Current chairs: acozine alongchamps felixfontein gundalow samccann
15:07:13 <acozine> felixfontein: welcome!
15:07:28 <acozine> #topic https://github.com/ansible/ansible/pull/56041
15:07:53 <felixfontein> thanks acozine!
15:08:03 <gundalow> Getting that to 60 PRs is amazing
15:08:18 <acozine> we are so close to 2 pages on GitHub
15:08:51 <acozine> if anyone has time to review stale PRs, that would be awesome
15:09:06 <acozine> I hate to leave good ideas and contributions "on the table"
15:09:24 <acozine> and even ones we don't merge have something to teach us
15:10:07 <acozine> but #56041 isn't stale at all
15:10:31 <acozine> the gist of it is: Change rendering of default list items in docs, so a list appears as ["myitem"] rather than [u'myitem']
15:10:57 <acozine> can anyone think of possible side-effects from this change?
15:12:19 <samccann> do you understand the change from "myitem" to ["myitem"]  (aka why we added brackets in 2.6?)
15:12:32 <felixfontein> as bcoca mentioned, both forms are not valid for ini-style option parameters (which I think are discouraged, but not deprecated)
15:12:34 <samccann> just out of curiosity.  As for side effects, I can't think of any
15:13:14 <acozine> samccann: IIRC the change was to demonstrate that the field is a list and can accept multiple values
15:13:18 <felixfontein> i.e.    dellos10_facts: gather_subset=['!config']    won't work
15:13:43 <acozine> felixfontein: ah, that is interesting
15:13:45 <felixfontein> but then this was already broken before the PR, so I guess the PR only improves the situation
15:13:54 <bcoca> felixfontein: some discourage, im not one of em
15:14:10 <samccann> https://www.irccloud.com/pastebin/35ikKjot/
15:14:10 <acozine> felixfontein: yep, sometimes we need to take small steps
15:14:32 <bcoca> convert lists into , separated strings, this works on all k=v and k: v cases
15:14:43 <samccann> so I think the examples are all in yaml, correct (aka we are consistent with that)
15:14:58 <bcoca> but table also includes 'ini' settings
15:15:04 <felixfontein> samccann: you can also write
15:15:09 <felixfontein> dellos10_facts:
15:15:17 <felixfontein> gather_subset: ['!config']
15:15:42 <acozine> bcoca: would it be more correct to strip the `[` and display just `!config` - would that work for both YAML and INI?
15:15:55 <bcoca> only if default is single value
15:16:07 <bcoca> i.e default: ['all', '!config']
15:16:10 <felixfontein> do values starting with ! have to be escaped in YAML? I can never remember that...
15:16:17 <bcoca> felixfontein: yes
15:16:29 <bcoca> !stuff is 'custom yaml parser hook'
15:16:30 <felixfontein> so if the default is a list, do ',
15:16:32 <bcoca> see !unsafe
15:16:38 <felixfontein> ','.join([str(e) for e in list])
15:16:49 <bcoca> s/str/to_text/
15:16:52 <felixfontein> ah, tojson instead of str
15:17:13 <felixfontein> to_text and str will both result in !config instead of "!config"
15:17:31 <bcoca> you need quoting also
15:17:37 <bcoca> but that can happen on the full string
15:17:47 <bcoca> i.e default: "!config, all"
15:17:57 <felixfontein> hmm. actually. doesn't ansible do all kind of YAML parsing of option values? so does ['!config'] really doesn't work for INI-style params?
15:18:33 <bcoca> !config does not require escaping in ini style
15:18:37 <bcoca> if that is what you are asking
15:18:45 <bcoca> subset=!config <<= safe
15:18:51 <bcoca> subset: !config <= not safe
15:19:19 <felixfontein> - debug: var=["!config"]    works fine for me
15:19:23 <acozine> is it possible to pass multiple values with INI-style syntax? if so, do we document that anywhere?
15:19:34 <felixfontein> so tojson (as in the PR) would produce a valid result
15:19:58 <felixfontein> while     - debug: var=[u"!config"]    fails
15:20:29 <Pilou> Could not "Choices/Defaults (YAML)" be added in the table header ?
15:20:59 <acozine> Pilou: that's a good idea
15:21:17 <acozine> do we have a sense of how many users still use INI syntax?
15:22:00 <acozine> maybe a blog post would be a good way to push for change and help people understand the details
15:22:43 <Pilou> a note could be added "Choices/Defaults (YAML, <link to a section with YAML & ini examples>)"
15:23:35 <samccann> if we prefer people don't use ini, should we/do we need to add more ini info (if it's not already there)?  I like the idea of saying the table is in YAML for sure to make that clear
15:24:05 <felixfontein> as I understood bcoca, not everyone prefers people to not use INI
15:24:09 <samccann> Not sure what the effect of a link might be - isn't this the same content served by ansible-doc?
15:24:15 <andersson007_> Greetings!
15:24:26 <bcoca> i actually prefer ini in some contexts
15:24:42 <acozine> andersson007_: hi!
15:24:46 <acozine> #chair andersson007_
15:24:46 <zodbot> Current chairs: acozine alongchamps andersson007_ felixfontein gundalow samccann
15:25:15 <felixfontein> ansible-doc already seems to use tojson, or something else, at least it outputs  [Default: ['!config']]  for that option
15:25:16 <andersson007_> acozine: Thanks!
15:25:20 * bcoca deprecates gather_subset and solves the issue
15:25:38 <samccann> Putting on my techwriter hat here - it's common practice to pick the 'best way' so to speak, for most of the documentation.  Then the 'alternate way' can be mentioned, but not emphasized.  Except where ini might be preferred/the better way in some instances/scenarios
15:25:38 <acozine> um . . . how did we get to `gather_subset`?
15:25:56 <bcoca> ^ actually, that is an issue gather_subset is more complex, its not just a module option, its also a keyword and a ansible.cfg entry
15:26:40 <bcoca> samccann: understood, that is why i have not made it an issue that we are rewriting k=v syntax out of existance
15:26:55 <acozine> hm . . . maybe at AnsibleFest we can have a docs bounty-hunt for INI examples in the module docs
15:27:14 <bcoca> i create those all the time
15:27:28 <acozine> bcoca: create what all the time?
15:27:40 <bcoca> k=v examples
15:27:54 <bcoca> in many cases they are clearer than k: v
15:27:56 <acozine> why do you choose that syntax?
15:28:00 <acozine> hmmm
15:28:26 <acozine> so why do we prefer the YAML `k: v` version?
15:28:30 <bcoca> peopel are easily confused by indentation, but change the syntax and it becomes clear what is a 'task keyword' vs 'module option'
15:28:44 <acozine> oh, interesting
15:28:47 <bcoca> acozine: multline k=v is messy
15:28:48 <felixfontein> anyway, I think the PR is already a good first step, since it improves the situation, and doesn't make it worse
15:29:00 <bcoca> also escaping rules in k=v require extra \
15:29:57 <acozine> felixfontein: I agree that this PR is a step in the right direction
15:30:26 <acozine> +1 to merging #56041
15:30:35 <samccann> +1
15:30:38 <Pilou> +1
15:30:46 <felixfontein> also +1
15:30:54 <acozine> 4/0 so far, unless bcoca you're opposed?
15:31:01 <bcoca> +-0
15:31:04 <acozine> heh
15:31:35 <acozine> okay, I'm going to merge it
15:32:17 <acozine> I'll post here when the change gets published, and if anyone sees problems with it, please post links here!
15:33:52 <acozine> samccann: do you want to give an update on the version-changer work?
15:34:02 <samccann> sure
15:34:09 <acozine> #topic version changer for docs
15:34:12 <samccann> is the jenkins test build visible do you know?
15:34:26 <acozine> the build itself is not, but the test site is
15:34:33 <samccann> ok - http://docs.testing.ansible.com/ansible/latest/user_guide/index.html
15:35:15 <samccann> the version is still at the bottom for now. I fixed the urls so that it knows latest vs 2.7 etc.
15:36:02 <samccann> (it was hardcoded to latest before).  The test site still shows latest in the url but devel in the title... So I need to pick acozine's brain on that one.  And I'll test it on 2.7, 2.6 next just to be sure the back n forth work
15:36:19 <samccann> then it's on to figuring out if I can move it higher up on the navigation vs floating at the bottom
15:36:46 <samccann> and this is the wip pr for the curious - https://github.com/ansible/ansible/pull/55655
15:37:16 <samccann> (review comments always welcome in the pr... I'm hacking away/learning via google how to do most of this)
15:38:07 <acozine> I think testing the back and forth is more important as a next step than getting the box to be at the top
15:38:23 <samccann> yeah me  too
15:38:48 <acozine> this is good progress --- this has been on the wish list for so long!
15:39:32 <felixfontein> will three also be a version selection in 2.6, 2.7, and devel?
15:40:07 <felixfontein> and is there a 404 when you change to a page which doesn't exist in the selected version?
15:40:10 <samccann> if you mean will we have version selection in the 2.6 etc versions of the docsite, yes, that's the goal.  No later than that
15:40:29 <acozine> felixfontein: we hope so . . . we're pretty sure we can get it into 2.7 at least
15:40:33 <samccann> the default (old/plain/unhelpful) 404 page appears yes. there's in issue to make that better
15:40:48 <samccann> (github issue that is)
15:41:03 <felixfontein> it might be a good idea to first implement the 404, and then the version selection, since the version selection increases the number of 404 links
15:41:11 <acozine> https://github.com/ansible/ansible/issues/51439
15:41:18 <acozine> that's the 404 issue ^^^
15:41:32 <felixfontein> 404 issue not found? ;)
15:41:39 <acozine> heh
15:41:49 <samccann> I'd like to get the version working first, even if we don't merge... so I don't forget what I was doing etc.
15:42:04 <acozine> yeah, the 404 is at least a known fix
15:42:12 <samccann> but how do others feel about getting a better 404 in place/merged first?
15:42:22 <acozine> I mean, there are no technical blockers, it's just work
15:42:36 <alongchamps> +1 on better 404 first, it will probably be helpful
15:42:40 <felixfontein> getting the version selector into a mergeable shape (if it isn't already) is totally fine with me
15:43:03 <acozine> +1 on the merge order, but keep working on the version-changer
15:43:25 <samccann> sounds like a plan, stan
15:43:28 <acozine> and if any community folks have time to work on the 404, that would be awesome!
15:43:31 <acozine> (hint, hint)
15:44:19 <acozine> I tried to describe a minimum viable fix in the issue, but I suspect others on this channel have more experience and more knowledge in this area than I do
15:45:26 <acozine> hey, with the merge of #56041 we are down to 59 open docs PRs
15:45:53 <acozine> there's something so satisfying about breaking another "decade"
15:46:05 * acozine does a little dance
15:46:06 <samccann> \o/
15:46:53 <acozine> thanks samccann for the update on the version-changer stuff - can you put a note on the PR documenting that we'd like to see the 404 work done and merged before we merge the version-changer?
15:47:06 <samccann> can do cashew
15:47:11 <acozine> heh, thanks!
15:47:19 <acozine> #topic open floor
15:47:21 * samccann glares at tea and wonders what's inside it
15:48:08 <acozine> I saw an article this morning about how Colorado is debating legalizing magic mushrooms . . . maybe your tea came from an experimental facility there?
15:48:47 <samccann> hehe could be!
15:48:53 <acozine> so . . . anybody have an issue, PR, suggestion, comment, idea, etc. to bring up?
15:49:09 <acozine> complaints? celebrations?
15:49:46 <acozine> I posted this last week, but it's worth posting again
15:50:18 <acozine> AnsibleFest call for proposals: https://ansiblefest2019.eventpoint.com/cfp
15:50:45 <acozine> it would be great to have a bunch of docs champions turn up in Atlanta
15:51:13 <acozine> who's planning to come to AnsibleFest 2019?
15:54:41 <acozine> well, if you have ideas for docs-related talks, i encourage you either to submit them, or to suggest them here!
15:54:54 <acozine> (presenters get free registration)
15:56:05 <acozine> and that brings us to the end of another DaWGs meeting (DaWGs walk? DaWGs romp?)
15:56:18 <acozine> thanks everyone, especially #chair
15:56:23 <acozine> hm, that didn't work
15:56:27 <acozine> thanks to . . .
15:56:30 <acozine> #chair
15:56:30 <zodbot> Current chairs: acozine alongchamps andersson007_ felixfontein gundalow samccann
15:56:48 <acozine> and to everyone following along at home
15:56:53 <samccann> :-)
15:57:19 <acozine> add agenda items for next week (or any week) to https://github.com/ansible/community/issues/389
15:57:26 <acozine> thanks again, folks!
15:57:30 <acozine> #endmeeting