14:31:19 <acozine> #startmeeting DaWGs aka Docs Working Group
14:31:19 <zodbot> Meeting started Tue Sep 17 14:31:19 2019 UTC.
14:31:19 <zodbot> This meeting is logged and archived in a public location.
14:31:19 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:19 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:19 <zodbot> The meeting name has been set to 'dawgs_aka_docs_working_group'
14:31:31 <acozine> #chair gundalow samccann
14:31:31 <zodbot> Current chairs: acozine gundalow samccann
14:31:35 <acozine> who else is around?
14:31:42 <bcoca> not me
14:31:57 <acozine> tough luck coca, you get turned into furniture anyway
14:32:01 <samccann> I C U!!
14:32:02 <acozine> #chair bcoca
14:32:02 <zodbot> Current chairs: acozine bcoca gundalow samccann
14:33:01 <acozine> nothing added to the agenda from the community issue
14:33:20 <acozine> for future reference, anyone can add agenda items to https://github.com/ansible/community/issues/389
14:33:54 <acozine> I'd like to call out andersson007_ for his heroic work on fixing typos in the module documentation
14:34:11 <acozine> thank you andersson007_ for all the painstaking, careful work you put in
14:34:25 <samccann> woot!!
14:34:42 <andersson007_> acozine: thanks! I’m happy it has been done:)
14:34:47 <bcoca> no one thanks me for creating the typos for him to fix?
14:34:51 * bcoca hugs andersson007_
14:35:03 <acozine> bcoca: you cannot possibly have created all of them
14:35:15 <andersson007_> bcoca: thank you! But it wasn’t a typo:)
14:35:32 <bcoca> acozine:  im not alone!
14:36:02 <acozine> heh, nope, everyone makes typos
14:36:08 <samccann> he is legion!
14:36:15 <acozine> many people follow up on the original typos by copying and pasting them into many files
14:36:27 <samccann> given how many typos I generate in a day... we are legion!
14:36:29 <andersson007_> I previously fixed mine:)
14:36:32 <acozine> or maybe the typos themselves just breed, who knows?
14:37:09 <andersson007_> Will do it next year again:)
14:37:34 <acozine> awesome!
14:37:55 <acozine> typos will always be with us, it's nice to know that typo hunters will too
14:38:31 <acozine> I'd also like to announce that DaWGs has a logo now
14:38:44 <acozine> we've had stickers made, and I'll be bringing them to AnsibleFest
14:39:12 <acozine> if you're coming to Atlanta, find me and I'll make sure you get some
14:40:12 <andersson007_> Thank you!
14:40:21 <acozine> andersson007_: are you coming to Fest?
14:42:14 <andersson007_> acozine: Unfortunately no, because it is a challenge to get the visa here. If officials reject my request it might be impossible to get it in the future
14:42:24 <acozine> andersson007_: ugh, sorry about that
14:42:37 <andersson007_> Np:)
14:42:58 <andersson007_> Anyway I should improve my English before that :)
14:43:09 <andersson007_> Maybe next time :)
14:43:13 <acozine> I hope so!
14:43:39 <acozine> meanwhile if you'd like some stickers, IM me and I'll mail them
14:44:36 <acozine> last item I had for today's agenda is a call for comments on the WIP changes to the User Guide pages
14:45:36 <acozine> it's not a PR yet, but the branch is here: https://github.com/acozine/ansible/tree/user_guide_overhaul
14:45:38 <andersson007_> Ok, would be cool ! I’ll send my contacts to you later, thanks!
14:45:49 <acozine> excellent!
14:46:29 <acozine> current round of changes is on the `devel` version of the docs testing site at http://docs.testing.ansible.com/ansible/latest/user_guide/index.html
14:47:09 <acozine> ah, wait, that's the `latest` version I linked
14:47:11 <acozine> hang on
14:47:29 <acozine> here we go: http://docs.testing.ansible.com/ansible/devel/user_guide/index.html
14:47:43 <acozine> vs. current published at http://docs.ansible.com/ansible/devel/user_guide/index.html
14:47:51 <tributarian> acozine: This is good stuff. I like the high level flow.
14:48:16 <acozine> tributarian: thanks
14:48:19 <acozine> oh
14:48:26 <acozine> #chair andersson007_ tributarian
14:48:26 <zodbot> Current chairs: acozine andersson007_ bcoca gundalow samccann tributarian
14:49:08 <acozine> feel free to nominate pages for revision
14:49:11 <samccann> big improvement acozine
14:49:27 <acozine> I'm working on the "Working with patterns" page now and have some feedback to incorporate
14:49:37 <acozine> hope to open a PR by Friday
14:50:13 <acozine> biggest change is I turned the long list of examples into a table
14:51:02 <acozine> next thing to fix is to tie it more closely to inventory, since the example patterns only work if the hosts/groups exist in inventory
14:52:56 <acozine> oh, I never set a topic
14:53:01 <tributarian> This taxonomy should make contributing easier.
14:53:33 <acozine> tributarian: that's great, what taxonomy do you mean?
14:55:10 <acozine> speaking of contributing, I saw a PR yesterday that updates the inventory page - I need to look at it and see if I can incorporate it into my rewrite easily
14:56:14 <acozine> ah, looks like bcoca and samccann have reviewed it
14:56:19 <acozine> https://github.com/ansible/ansible/pull/62323/files
14:57:49 <acozine> #topic open floor
14:58:10 <acozine> what's on your minds, folks?
14:58:57 <samccann> I got the logo up on our wiki - https://github.com/ansible/community/wiki/Docs
14:58:59 <samccann> :-)
14:59:03 <acozine> w00t!
14:59:32 <tributarian> acozine: I was mistaken on the taxonomy. The TOC hasn't changed as much as I thought. The changes are great though.
15:00:21 <acozine> tributarian: yeah, the TOC seems pretty good, but the content needs cleaning up, and more "connective tissue" from one page to another would help
15:00:37 <acozine> and some better titles
15:01:09 <acozine> "Working with patterns" doesn't give the new reader any idea of why that content would be useful for her
15:01:16 <samccann> which TOC are we talking now? user guide?
15:01:23 <tributarian> Yes
15:02:14 <samccann> can you elaborate on what you were hoping for in an updated TOC?
15:02:32 <acozine> I think we were agreeing that it's pretty good
15:02:43 <tributarian> acozine: The pattern changes are especially good. I find myself referring back to the pattern documentation often.
15:02:44 <samccann> ah ok... my mistake
15:03:16 <tributarian> samccann: It is more that the TOC has been updated since the last time I saw it. (a long time ago) I mostly use search.
15:03:31 <acozine> tributarian: most people do
15:04:21 <samccann> speaking of search... we are experimenting with moving the lower-left search into the upper right search (they use two different search engines)
15:04:22 <acozine> what would folks think of adding more levels to the User Guide TOC, so the top-level sections were `Working with inventory` and `Working with playbooks` and then the other pages were under those in the TOC?
15:04:59 <samccann> I do find the current length of the user guide TOC a bit ...daunting
15:05:28 <acozine> oh, right - tributarian when you say search, do you mean searching on Google/DuckDuckGo/other search platform? or do you use the docs.ansible.com site search?
15:06:08 <acozine> ^^^ is a question for everyone
15:06:24 <acozine> (not just tributarian)
15:06:36 <tributarian> I primarily use google search as I find it produces generally more relevant results.
15:06:59 <tributarian> If I'm already on a page, Ill sometimes use the top left search.
15:08:06 <acozine> is your preference for top left just because of location? or because the engine produces better results?
15:08:16 <tributarian> Although, I just tried "Search this site" and the results are far better. Namely, it returns some of the page content and not just page titles.
15:08:33 <tributarian> It is definitely the more eye-catching search option on the page.
15:08:34 <samccann> yes that's one of the reasons we want to switch to that search engine
15:08:42 <tributarian> I would agree with that move.
15:09:32 <samccann> #info - investigating move the site search (lower left) to replace the search box in the upper right on docs.ansible.com
15:10:38 <samccann> sorry to derail the user guide TOC discussion
15:11:05 <acozine> samccann: the search discussion is an important one, glad you brought it up!
15:11:08 <samccann> but for the user guide, I'd be in favor of simplifying the TOC if possible to some high-level sections etcc
15:12:50 <samccann> I also wonder - could we move ad-hoc and cli commands into the getting started section?
15:13:28 <acozine> that's a good idea
15:14:28 <tributarian> I would say keep the CLI commands section and move the ad-hoc commands under the ansible cli tool
15:14:40 <tributarian> And make the quickstart a child of getting started
15:15:21 <samccann> hmm. The individual cli pages are autogenerated.
15:15:53 <tributarian> ah, i see that now
15:15:54 <acozine> tributarian: where do you mean by "under the ansible cli tool"
15:16:11 <samccann> though I see the connection between 'ansible' in the cli section, and the adhoc content etc
15:16:33 <samccann> https://docs.ansible.com/ansible/devel/cli/ansible.html
15:17:49 <tributarian> Yeah that was the page I was thinking, but I understand that it is auto generated.
15:18:11 <tributarian> I think having the list of commands front and center is good.
15:19:18 <acozine> it looks like most of the examples on https://docs.ansible.com/ansible/latest/user_guide/intro_adhoc.html are for `ansible`
15:19:30 <samccann> was just about to type that :-)
15:20:04 <samccann> we might be able to put ad-hoc below the ansible cli page... but would that disrupt the flow of the cli section? (aka is it worth it?)
15:20:44 <acozine> we could add it at the end of the cli section as "examples of `ansible` commands"
15:22:11 <acozine> or put it in the Getting Started section as samccann suggested - it makes a nice flow to say "here are some things you can do at the command line . . . if you do these tasks repeatedly, you want to turn them into playbooks" and then transition to the playbooks section
15:23:55 <acozine> then at the end of the playbooks section introduce the idea that "now you want to be able to run that playbook on some servers and not on others . . . Ansible lets you control that with inventory"
15:24:53 <samccann> okay just did a quick check of our docsite hits and the ad-hoc page gets about 5% of our total website hits (23rd most visited page)
15:25:12 <acozine> huh, that's higher than I expected
15:25:26 <samccann> yeah same here!  So we should 'proceed with caution'.
15:25:44 <acozine> well, we can move it around in the TOC without disrupting most of that traffic
15:25:52 <samccann> yeah was thinking that.
15:25:53 <acozine> as long as we keep the page name the same
15:26:28 <acozine> my guess is that people use that page as a reference/reminder
15:27:50 <acozine> we have three minutes left
15:28:18 <acozine> any other topics/ideas/concerns/questions folks want to bring up?
15:29:34 <acozine> thanks everyone for your support for Ansible docs!
15:30:06 <acozine> thanks especially to samccann tributarian andersson007_ bcoca for participating in today's meeting
15:30:25 <acozine> we'll post the minutes at https://github.com/ansible/community/issues/389
15:30:43 <acozine> hope to see some folks in person in Atlanta for AnsibleFest
15:31:26 <acozine> add agenda items for next week - PR review, issue triage, brainstorming, all items welcome!
15:31:40 <acozine> #endmeeting