14:31:10 <samccann> #startmeeting Docs Working Group aka DaWGs
14:31:10 <zodbot> Meeting started Tue Jul 30 14:31:10 2019 UTC.
14:31:10 <zodbot> This meeting is logged and archived in a public location.
14:31:10 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:10 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:10 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:26 <samccann> who's around today to talk docs?
14:34:24 <samccann> hmm... nobody?  nobody at all?
14:35:03 <tributarian> I'm here, but I was a couple minutes late.
14:35:17 <samccann> welcome tributarian !!
14:35:57 <samccann> Since it may be just the two of us - was there something in particular you wanted to discuss in ansible docs land?
14:36:20 <tributarian> I'm more here to observe and look for places I can lend a hand.
14:36:27 <samccann> ok kewl!
14:36:36 <tributarian> I found the docs label in issues yesterday
14:36:39 <samccann> #topic Open Issues
14:37:04 <samccann> To start, we have a backlog of issues here - #link https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs
14:37:27 <samccann> we've been trying to identify and label 'easyfix' items but I think we have to go through and find some more
14:37:46 <tributarian> should I avoid things with an assignee?
14:38:13 <samccann> not necessarily.  If it's something you think you can help with, add a comment directed at the assignee
14:38:48 <samccann> sometimes we self-assign and then get bogged down somewhere else.  Other times we are active in the background, so that comment check before you get started is worth it
14:39:24 <samccann> This is one I've been looking to see if someone can give it a try - https://github.com/ansible/ansible/issues/51847
14:40:09 <samccann> I'm not sure how to test what `fetch` does to verify and improve the docs to match
14:40:25 <tributarian> ah
14:41:01 <samccann> :-) no worries if that's not your cup of tea either.  just tossing it out there for anyone reading the meeting logs later too
14:41:18 <tributarian> that i can probably help with if it is just identifying the behavior
14:41:28 <tributarian> i have used that module before
14:41:42 <tributarian> so we just need to look at the edge case and write down what happens then
14:41:49 <samccann> that would be great then!  you can put a comment in the issue on what you find.
14:42:23 <tributarian> cool, ill take a look. ill spin up my vm in the lab and update it with what i find
14:42:38 <samccann> Then if you are up for it, you could open a docs PR if needed to clarify how it works.
14:42:53 <samccann> #link https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#community-documentation-contributions  has all the details if you decide to open a docs PR
14:43:18 <tributarian> awesome, i would expect no less from the documentation group ;)
14:43:19 <samccann> but even if you don't, just having someone validate how it works in the issue comments means someone else can easily pick up the doc fix
14:43:25 <samccann> HAHAH
14:43:34 <samccann> we luv words!!
14:43:44 <samccann> esp. the right words ;-)
14:43:55 <tributarian> I love documenation precisely because it gets so little love
14:44:09 <samccann> woot!!
14:44:11 <tributarian> Ansible's documentation has always impressed me
14:44:46 <samccann> thanks!  it's a real community effort. A few of us champion and move things along, but it's really people like you and others who make it what it is (useful and accurate!)
14:45:35 <tributarian> I read somewhere that a huge percentage of quality fixes to wikipedia come from first time contributors.
14:45:51 <samccann> could be!
14:46:14 <samccann> feel free to wander through that issues list and investigate anything that holds your interest.
14:46:51 <samccann> and we're here whenever you have questions/comments/ etc
14:46:56 <tributarian> cool thanks
14:47:39 <samccann> #topic Translation requirements
14:48:01 <samccann> We brought this up last week, but there may be the chance to have the ansible docs translated into Japanese.
14:48:20 <samccann> This brings up some things we have to get better about doing in our docs.  The two top items right now:
14:49:21 <samccann> 1 - use codeblocks :-)  Sometimes we can get the same look/feel w/o the codeblock, but that means the machine translation tries to translate our code snippets.  if we keep them in `code_block` then the translation knows to skip that
14:50:34 <samccann> #info keep code snippets inside `code-block` so translation ignores that text
14:51:24 <samccann> 2. Keep text outside of a `code-block`  - if you are describing something, make sure that's not in the `code-block` or it won't get translated.  See https://github.com/ansible/ansible/issues/59449 for details
14:51:41 <samccann> #info avoid comments inside the `code-block` if possible so they can be translated
14:51:56 <samccann> oph.. there's a third.
14:52:22 <samccann> 3. don't use contractions :-)  harder to translate.  There are likely more we'll have to keep an eye on, but these have come up already.
14:53:44 <tributarian> Is there a preference, when dealing with lists of steps, to have a `code-block` per step or have a summary block at the end?
14:54:29 <samccann> hmm. I think that would depend on the example really.
14:55:23 <samccann> if it's most useful to the end user to be able to copy/paste that summary block at the end, and then edit for their use case, then probably at the end.  But if it's complex, and is more helpful to understand things to have a step and a `code-block` then use that approach
14:56:41 <samccann> Also keep in mind that google search tends to like steps :-)  So it's possible that set of steps will show up at the top of a google search by itself  like this - https://www.google.com/search?q=how+to+make+scrambled+eggs&ie=utf-8&oe=utf-8&client=firefox-b-1-e
14:57:03 <samccann> in that case, the summary at the end might not show up in the search result
14:57:31 <samccann> (which is my very long answer that should have said ' use your judgement' :-)
15:00:25 <samccann> #topic How to report Bugs (issue https://github.com/ansible/ansible/issues/53520)
15:00:57 <samccann> This is another open issue that's been around awhile. I'm thinking we may be able to fix it in pieces (different PRs) to chisel away at the wish list there
15:02:49 <samccann> I'll probably keep that one on the agenda for a few weeks to see who might be interested in taking tidbits from it  to fix.
15:03:43 <samccann> #topic Open Floor
15:03:53 <samccann> Anything else we want to chat about today?
15:05:09 <samccann> I'll toss out the PR backlog - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs  if anything there is of interest that you want to review/test/comment on, help is always welcome there as well
15:05:31 <samccann> typically we avoid [WIP] and anything with a red x as stuff not ready to merge yet.
15:07:47 <samccann> ok gonna close the meeting... going once...
15:08:19 <samccann> going twice....
15:08:38 <samccann> #endmeeting