14:32:02 <acozine> #startmeeting Docs Working Group aka DaWGs
14:32:02 <zodbot> Meeting started Tue Jan 14 14:32:02 2020 UTC.
14:32:02 <zodbot> This meeting is logged and archived in a public location.
14:32:02 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:32:02 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:32:02 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:32:09 <acozine> who's around?
14:32:14 <cbudz_> I am
14:32:15 <samccann> o/
14:32:24 <acozine> #chair cbudz samccann
14:32:24 <zodbot> Current chairs: acozine cbudz samccann
14:32:33 <acozine> !
14:32:45 <acozine> sorry, I'm typing on an actual laptop today
14:32:49 <acozine> it's gonna get messy
14:32:59 <acozine> I'm so used to my split keyboard
14:32:59 <cbudz_> It's funny how tough that is sometimes
14:33:16 <acozine> meant to type "welcome cbudz" and apparenlyt I hit some weird key
14:33:21 <acozine> aaaargh
14:33:25 <acozine> well, you know what I meant
14:33:42 <cbudz_> all is well
14:33:56 <acozine> any folks around on the far side of the pond?
14:34:10 <acozine> andersson007_: shaps Xaroth ?
14:34:26 <acozine> felixfontein: you around?
14:34:48 <acozine> I see some new nicks I havne't noticed before
14:35:00 <acozine> PeatTheB33t: welcome to Ansible docs chat
14:36:06 <acozine> dfed[m]: epereira_ jhawkesworth madonius Pilou tremble xenlo zbr zoredache zyun
14:36:22 <acozine> I'm going to ping everyone
14:36:45 <samccann> a ping party!
14:37:21 <samccann> back in the day, we used to have actual ping parties... when a new piece of hardware was pingable... then there was beer and food and fun
14:37:31 <acozine> as always, our agenda is the last comment on https://github.com/ansible/community/issues/389
14:37:39 <acozine> samccann: that sounds fun
14:38:16 <samccann> it was... tho I do seem to recall walking between buildings at the Cisco campus with a pylon cone on my head... so you know... poor choices etc
14:38:45 <acozine> heh, was that the result of too much partying, or was that some kind of Cisco hazing ritual?
14:38:52 <samccann> too much booze
14:39:06 <bcoca> driveby: add new 'advanced' or 'deep dive' page that describes ansbile's inner workings on how we loop through plays/tasks and what happens at each stage .. mostly that will clarify why undefined in loop is not captured by when and other 'mysteries'
14:39:24 <acozine> bcoca: thanks for dropping in
14:39:53 <bcoca> as always, conflicting meetings, so will not be 100% here
14:39:54 <acozine> this week's agenda is short: https://github.com/ansible/community/issues/389#issuecomment-571631490
14:39:59 <samccann> #info add new 'advanced' or 'deep dive' page that describes ansbile's inner workings on how we loop through plays/tasks and what happens at each stage .. mostly that will clarify why undefined in loop is not captured by when and other 'mysteries'  (bcoca)
14:40:06 <samccann> #topic Status Updates
14:40:22 <samccann> I can start with a couple of nibbly bits
14:40:34 <acozine> hang on, I tbink we have a page that might be the right home for what bcoca describes
14:40:42 <samccann> ok
14:40:45 <acozine> i'll dig for a link, you carry on
14:41:15 <samccann> #info top left search box on devel is now running swiftype search. Feedback most welcome
14:41:48 <samccann> we want to see how it works before considering backports etc. a little search experiment :-)
14:42:02 <samccann> #info Added writing guidelines for search optimization
14:42:05 <samccann> #link https://docs.ansible.com/ansible/devel/dev_guide/style_guide/search_hints.html
14:42:36 <samccann> so basically added to the Ansible style guide to help folks understand a few ideas on making their docs content more findable etc.
14:43:44 <acozine> aha! found it - https://docs.ansible.com/ansible/latest/dev_guide/developing_program_flow_modules.html
14:44:12 <acozine> that is probably where the "how ansible executes" stuff should go, or at least we should integrate the missing info with that page
14:44:28 <acozine> samccann: hooray for the SEO guidelines
14:44:43 <cbudz_> kudos on those. Saw that PR yesterday
14:44:48 <acozine> I will look at them every time I look at the headings-syntax page
14:45:06 <samccann> #topic how ansible executes
14:45:08 <acozine> so as I regularize the headers markings, I will try to make our docs more findable
14:45:15 <acozine> ooh, an actual topic
14:45:21 <acozine> cool!
14:45:24 <samccann> #link https://docs.ansible.com/ansible/latest/dev_guide/developing_program_flow_modules.html
14:45:33 <samccann> well trying to keep the meeting minutes making sense :-)
14:45:40 <acozine> this topic came from a concern on Reddit, I think
14:45:45 <acozine> the question was . . .
14:46:07 <samccann> #info above link is a possible home for a deep dive on how ansible executes
14:46:15 <acozine> https://www.reddit.com/r/ansible/comments/eo6lwq/why_is_ansible_user_not_defined_when_accessed/fe9dcci/
14:47:11 <samccann> #link https://www.reddit.com/r/ansible/comments/eo6lwq/why_is_ansible_user_not_defined_when_accessed/fe9dcci/  - where the request came from
14:47:50 <acozine> and the answer is, as I understand it, that because some users want the values of a variable to vary from one item in the loop to another, Ansible doesn't "carry over" the first-defined value
14:48:16 <acozine> so . . . loops are powerful, and their behavior is not always well-understood
14:48:34 <acozine> the behavior of loops is tied to the way ansible executes
14:49:00 <acozine> so links between thbe loops page and the how-ansible-executes info would also be good
14:49:13 <acozine> I"m givinfg up on typos in things where I tink it's obvious what I meant
14:49:27 <acozine> otherwise this keyboard will send me over the edge
14:49:38 <samccann> only part way through the thread, but this seems to be a user question, not a developer question (that is, not an ansible module/collection developer question). So would somthing in the dev guide be findable by a user?
14:49:44 <bcoca> acozine: welcome to the dark side!
14:50:06 <acozine> bcoca: you mean the laptop keyboard, or delving into how ansible executes?
14:50:19 <samccann> all dark... ALLL DARK!!!
14:50:27 <bcoca> ignoring typos
14:50:28 <bcoca> ...
14:50:40 <acozine> heh, jsut as you typed that, a light went on in the office hallway
14:50:47 <samccann> lol
14:50:50 <acozine> I tink someone else is here in the office with me
14:51:00 <samccann> acozine now sees the light and shall mend her ways
14:51:12 <acozine> can't hear or see them yet, but . . .
14:51:21 <acozine> heh, I make no mending-ways promises
14:51:29 <samccann> REPENT!
14:51:42 <samccann> i am perhaps digressing the thread here... :-P
14:51:48 <acozine> anyway, your point about user questions vs developer questions is vlaid
14:51:49 <acozine> valid
14:52:10 <acozine> but sometimes user requirements send them off into the weeds
14:52:21 <bcoca> we can have 2 pages, user detail level and then expand to developer detail level
14:52:23 <acozine> and how else will we recruit the module develoeprs of hte future???
14:52:44 <acozine> bcoca: sure, we can try that
14:52:45 * bcoca thinks of unmarked van and strong dark bag as hood
14:52:55 <acozine> heh
14:53:31 <acozine> I prefer a glowing box and the thrill of victory as lures
14:53:51 <bcoca> those are not either/or propositions
14:53:54 <samccann> offer cookies... people always come for cookies
14:53:57 <acozine> if that's how they're recruited, they generally stay without being chianed u
14:54:01 <acozine> chained up
14:54:09 <acozine> but we digress . . .
14:54:20 <acozine> what is our topic, again?
14:54:30 <samccann> the reddit thread
14:55:08 <bcoca> https://www.reddit.com/r/ansible/comments/eo6lwq/why_is_ansible_user_not_defined_when_accessed/
14:55:20 <samccann> #info consider a user level page to introduce the ansible execution tidbits, then a deeper dive in the dev guide
14:55:26 <bcoca> ^ this and a copule of other issues always come up, mostly due to misunderstanding how the loop works and the 'stages' of a task
14:55:36 <bcoca> loop > when > connection
14:55:57 <acozine> anybody interested in doing a draft of this topic?
14:56:10 <cbudz_> sure
14:56:27 <samccann> cbudz_ FTW!
14:56:30 <acozine> cbudz_: great!
14:56:46 <samccann> #action cbudz to draft a topic to cover this
14:58:07 <acozine> #topic latest user guide updates
14:58:41 <acozine> I've done another round of revisions to the User Guide pages
14:58:45 <acozine> PR: https://github.com/ansible/ansible/pull/66371
14:59:07 <acozine> New pages are up on the testing site in the `devel` branch ONLY
15:00:16 <acozine> http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_reuse.html
15:00:48 <acozine> that page is the one I'd most like feedback on
15:01:40 <acozine> big changes to http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_reuse_roles.html
15:02:11 <zbr> o/ we do have open topic at the end?
15:02:20 <samccann> #info looking for feedback on https://github.com/ansible/ansible/pull/66371
15:02:30 <acozine> and also to http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_tags.html
15:02:37 <samccann> #link http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_reuse_roles.html especially
15:02:39 <acozine> zbr: yes!
15:02:44 <acozine> we always have open floor
15:02:52 <samccann> #link http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_tags.html as well
15:03:02 <acozine> also, you can propose a topic ahead of time on the agenda
15:03:11 <acozine> zbr: ^^^
15:03:22 <acozine> also, welcome zbr!
15:04:02 <zbr> acozine: thanks. now that i registered I will not miss the meetings, maybe only their start.
15:04:24 <zbr> idea: can we start running ansible-lint on docs examples? so we assure that what we recommend users is always the best way to write it? (obviously that goes both ways - as in updating linter to match recommended style when needed).
15:05:04 <acozine> zbr: cool, let's discuss that nex
15:05:05 <acozine> next
15:05:49 <acozine> to close out the topic of the User Guide changes . . .
15:05:55 <acozine> all reviews welcome
15:06:07 <acozine> comments, questions, suggestions
15:06:16 <acozine> feel free to post them here @ me
15:06:24 <acozine> or put them directly on the PR in GitHub
15:06:43 <acozine> #topic linting examples in the documentation
15:07:12 <samccann> This is an idea we tossed around before.
15:07:18 <acozine> we have discussed this a few times
15:07:34 <samccann> as I recall, it requires moving the examples into separate files in a directory, then running ansible-lint against them
15:08:00 <zbr> reasoning: people copy/paste a lot from docs, any example that is using less than best guidelines, would likely make users write worse code.
15:08:07 <acozine> one of gthe best solutions I've heard proposed is that we make tests double as docs examples
15:08:07 <samccann> but, as I think about it now, I wonder if there is a way to run ansible-lint against the module examples ...with a bit of scripting magic?
15:08:18 <acozine> that way the examples would always be maintained
15:08:30 <zbr> moving to files may be needed for parsing/linting but I not a goal bit itself. is more a technical aspect I think.
15:08:33 <samccann> zbr oh definitely agree and it's something we've wanted to do... it's the logistics of it that trap us so to speak
15:08:48 <acozine> I'm not sure how to make the our-tests-are-also-our-examples approach work from a technical viewpoint
15:09:07 <zbr> lets create a ticket for it, note what is agreen upon and maybe we can start marking small PRs towards that goal.
15:09:11 <acozine> zbr: yes, it's a great idea, would be very helpful
15:09:17 <samccann> now that I think about a scripting solution - could we write a script that just scrapes through the .rst files, searches for code-block yaml and then runs ansible-lint against all of them?
15:09:44 <acozine> hmmm, would we have to make all the examples full playbooks?
15:09:47 <samccann> i'm not sure all yaml code-blocks are ansible (inventories etc)
15:09:57 <samccann> i'm not sure ansible-lint is that specific
15:10:09 <acozine> mm, htat's true
15:10:19 <samccann> but I could be wrong. easy enuf to pull out a few examples that aren't full playbooks and see what happens.
15:10:21 <acozine> well zbr are you willing to open the issue?
15:10:39 <zbr> it can be hinted, but linting examples does not limit to ansible-lint itself, also applies to other linters like yamllint or flake8.
15:11:24 <samccann> #info would be great to run ansible-lint against doc examples in .rst and module docstrings. May require some scripts to do this w/o having to move all examples into separate .yml files
15:11:32 <acozine> I like the idea of "drinking our own champagne" and using the docs examples with ansible-lint to make sure we keep ansible-lint usable
15:11:47 <zbr> writing now the ticket...
15:11:54 <acozine> zbr: excellent!
15:13:06 <acozine> I hope we can do the updates in stages
15:13:22 <acozine> maybe start with a smaller section of the docs, then work our way up to full coverage
15:13:44 <acozine> we'll need a proof-of-concept to start with
15:14:04 <cbudz_> Are there usage stats to taget higher usage docs with examples to start with?
15:14:16 <samccann> why yes there is cbudz!
15:14:21 <samccann> looking for a link...
15:14:33 <cbudz_> *target
15:15:00 <samccann> #link https://github.com/ansible/ansible/issues/58687  - lists top 10 doc pages for Ansible. Good place to start making improvements
15:15:06 <acozine> samccann is our stats guru
15:15:21 <samccann> I should run the stats again since that's 6 months old now (my how time flies)
15:15:53 <acozine> I'll be interested to see if it has changed
15:16:52 <acozine> zbr: can you add a link from the test-the-examples issue to the top-ten-pages issue samccann just posted?
15:17:58 <zbr> https://github.com/ansible/ansible/issues/66474
15:18:11 <acozine> hooray! thanks zbr
15:18:44 <cbudz_> Have to drop to prepare for another status meeting, thanks all
15:19:09 <acozine> thanks cbudz!
15:19:23 <samccann> #link https://github.com/ansible/ansible/issues/66474 - new issue to track ansible-lint on docs
15:19:59 <acozine> I put a link across to samccann's top-ten iussue
15:20:01 <acozine> aaargh
15:20:02 <acozine> issue
15:20:21 <acozine> next time I come to the office I am bringing my external keyboard
15:20:21 <samccann> gonna be a long day for you
15:20:27 <acozine> no matter how geeky I look
15:20:34 <acozine> heh, yes, it is
15:20:43 <acozine> on the ohter hand, my finger muscles are getting a workout!
15:20:50 <samccann> silver lining
15:20:52 <acozine> esp. the right pinkie
15:20:56 <acozine> the one that hits backspace
15:21:01 <samccann> heh
15:22:00 <acozine> zbr: if you have ideas for how to implement linting docs examples, please bring them to this channel!
15:22:17 <acozine> meanwhile, anything else for today?
15:22:22 <acozine> #topic open floor
15:22:31 <samccann> I have one PR I think we can close
15:22:35 <acozine> awesome
15:22:37 <acozine> which one?
15:22:52 <samccann> https://github.com/ansible/ansible/pull/66408
15:23:17 <samccann> now that I read it, it has two folks saying the doc is fine as it is... so gonna just close it unless you see a reason to keep it open for debade?
15:23:25 <samccann> debate even (and I do have my tented keyboard)
15:25:42 <acozine> sounds okay to close
15:26:29 <acozine> samccann: go for it
15:26:43 <samccann> closed
15:27:10 <samccann> puts us down to 93 open PRs :-)
15:27:13 <acozine> does the main ansible-YAML page have a note about "there are different ways to indent"
15:27:20 <acozine> if not we could add one
15:27:49 <acozine> something about "there's more than one valid way to indent your YAML, and there are dozens of invalid ways too"
15:28:02 <acozine> 93, eh? that's going in the right direction!@
15:28:22 <acozine> anybody else have stuff today?
15:28:35 <samccann> nothing else here
15:28:47 <acozine> quiet day in docs-land
15:29:12 <acozine> all right, thanks bcoca cbudz_ samccann zbr !
15:29:22 <acozine> #endmeeting