15:01:53 <acozine> #startmeeting Docs Working Group aka DaWGs
15:01:53 <zodbot> Meeting started Tue Jul 23 15:01:53 2019 UTC.
15:01:53 <zodbot> This meeting is logged and archived in a public location.
15:01:53 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:53 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:53 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:01:59 <acozine> who's around?
15:02:08 <bcoca> im 1/4 around .. triage meeting
15:02:11 <samccann> o/
15:02:26 <acozine> #chair bcoca samccann
15:02:26 <zodbot> Current chairs: acozine bcoca samccann
15:02:49 <acozine> #topic docs team update
15:03:59 <acozine> a Japanese translation of the Ansible Engine documentation looks likely to happen for version 2.10 (spring of 2020)
15:04:31 <samccann> good times!
15:04:56 <acozine> we're looking at how/where to publish the translated docs, and at finding ways to make translating easier
15:05:25 <acozine> we've got one issue filed already: https://github.com/ansible/ansible/issues/59449
15:07:02 <acozine> ideas for making translation easier are very welcome - generally things that make translation easier also make the docs more predictable and readable, so it's a win for users of the English-language docs as well
15:09:01 <acozine> open docs PR numbers are fairly steady at or under 75 - it would be great to chip away at the backlog some more, but we're keeping up fairly well
15:09:20 <samccann> on translation - I'm assuming sphinx supports japanese, but do we know what version of sphinx?
15:09:33 <samccann> (aka what version tower uses cuz they already have japanese, right?)
15:10:12 <acozine> samccann: that's a good question - the translation team will be sending a one-page test file so we can work out the publication pipeline
15:10:37 <samccann> also, I'm guessing they will use machine translation right? which means rewrites etc cause retranslations each time (vs just picking the block out of translation memory)
15:11:08 <acozine> they are using a combination of machine translation and actual human translators
15:11:12 <samccann> I've done this w/ xml but and asciidoc but never rst
15:11:18 <samccann> yeah that's typical.
15:11:26 <samccann> (machine backed up by human)
15:12:13 <acozine> they are going to start with the Porting Guides, and may have those done in time for the release of 2.9 this fall
15:12:18 <samccann> I wonder - we have code that isn't in codeblocks ( I think I saw that). I wonder if we need another PR to make sure all code snippets are in codeblocks
15:12:53 <acozine> that would be a good step
15:13:16 <acozine> they will also leave anything within double-backticks un-translated
15:13:30 <acozine> so where we have `code` quoted within a sentence, it will remain in English
15:13:32 <samccann> ooo omgosh that's another one where there's plenty of room for mistakes etc
15:14:05 <acozine> it will be an adventure for sure
15:14:08 <samccann> we'll need to make a list of things that will help translation, and then how to address them etc.
15:14:24 <samccann> Are they planning on translating all rst files for 2.10?
15:14:30 <samccann> (nongenerated rst)
15:14:45 <acozine> it depends on how the first test goes, and on how many resources they get
15:14:50 <samccann> ah gotcha
15:15:09 <samccann> so we may need a priority list of guides to tackle
15:15:38 <acozine> that would be great - for now, it's not our top priority, but it's something I hope everyone will keep in mind as they write/revise docs pages
15:16:05 <acozine> I've told them to start with the Developer and Community guides, since those have the most updated content
15:16:35 <acozine> but we haven't reviewed them specifically for translatability (is that a word?)
15:18:15 <samccann> i think it is?  but yep, needs some thought on what helps and what hurts, and what will be actively being changed in 2.10.
15:18:49 <samccann> (because of collections etc)
15:19:00 <acozine> we also discussed the URL pattern for Japanese docs - on Tower they use URLs like https://docs.ansible.com/ansible-tower/3.4.3/html_ja/quickstart/
15:19:24 <acozine> samccann: yes, I told them not to try translating any module docs at this time because of the collections move
15:21:01 <acozine> they understand that our docs are actively updated; i don't know how much of an issue that will be moving forward
15:22:10 <acozine> anything else on translation?
15:22:33 <acozine> ideas/caveats/suggestions/etc?
15:22:47 <acozine> it's quiet in here today
15:22:56 <samccann> it will be interesting to see how they handle the more casual 'tone' of ansible docs
15:23:21 <samccann> ohmgosh ! ansible-docs!  I'm guessing that stays in English?
15:23:42 <samccann> as in no plan to make ansible engine itself bilingual?
15:24:05 <acozine> I don't know - if we were to fully internationalize Ansible, it wouldn't just be ansible-docs, but also things like warning messages . . . many of which come from the modules
15:24:22 * samccann nods
15:24:27 <acozine> if that's the goal, it will be a long process, and certainly not ready for 2.10
15:24:46 <samccann> guessing it isn't the goal.
15:26:00 <acozine> for now the goal is to translate the rST pages for 2.10; probably the response from the Japanese market will determine next steps
15:26:15 <samccann> speaking of quiet - before we move off docs updates - were we goiong to move this meeting earlier?
15:26:29 <acozine> yes, I think we should
15:26:48 <acozine> I keep waiting for a meeting when more folks are around to vote . . . and that keeps not happening
15:26:57 <acozine> so maybe we should just do it
15:27:03 <samccann> +1
15:27:09 <acozine> +1
15:27:20 <samccann> it used to be 1/2 hr earlier when I started
15:27:53 <acozine> we can do 1/2 hour earlier or full hour earlier
15:28:14 <acozine> I think starting on the hour is easier to remember
15:28:23 <samccann> I'm game for either. your preference.
15:28:27 <acozine> oh, but I'm on PTO for the next two Tuesdays
15:28:34 <samccann> HAHAH
15:28:39 * samccann gulp!!
15:28:42 <acozine> heh
15:28:58 <samccann> perfect time to move it then!
15:29:23 <acozine> sounds great, I think we should have a new time set and advertised before September
15:29:25 <samccann> as an experiment. W/o you here, could be slow meetings anyway. Either we'll get more peeps, or it will be me talkin to myself
15:29:30 <acozine> heh
15:30:26 <acozine> it would probably help to advertise the meetings more in the channel, and also to have agenda items in advance
15:31:08 <acozine> and maybe we're a victim of our own success - my impression is that the core meetings spend a lot of time on pending PRs, and we've kept up with docs PRs pretty well
15:31:30 <acozine> I looked at our stats last Friday . . .
15:32:29 <acozine> from August 16, 2018 to last Friday (not quite a year) we merged or closed 1,970 PRs labelled `docs`
15:32:52 <acozine> in the same period we closed 294 issues labelled `docs`
15:33:06 <samccann> WOOT!!
15:33:15 <acozine> that "we" includes many community committers and members of other Ansible teams
15:34:58 <acozine> that's about all I had for docs team updates
15:35:57 <acozine> #topic open floor
15:36:38 <samccann> should we brainstorm how to get more folks involved in this meeting? (besides the time shift)
15:37:16 <acozine> sure . . . how to get folks involved, what we (the docs team, the community) want to get out of these meetings
15:38:02 <samccann> yep.  Maybe we come prepared with a couple of issues to either discuss or look for volunteers to fix?  Or solicit agenda topics toward the end of each week to add to the Tues agenda?
15:38:13 <acozine> that's a good idea
15:40:06 <acozine> if we can find themes among the open issues, maybe we can focus collectively on a theme
15:40:25 <samccann> yeah I like that idea.
15:40:38 <samccann> I also want to get some of our search optimization lessons learned implemented.
15:40:48 <acozine> we did that for docsite fixes, and it worked well - we got discussion and ideas from multiple folks
15:41:07 <acozine> ah, yeah - you opened an issue for that, didn't you?
15:41:08 <samccann> hmm... now I wonder if we need a way to document search lessons learned somewhere so others can learn etc?
15:41:34 <acozine> that sounds kind of related to the translation stuff we were talking about earlier
15:41:34 <samccann> I 'think' i did. But we had two sessions now.. not sure I opened an issue on the second session
15:42:22 <acozine> maybe new pages for the Style Guide covering things to keep in mind for SEO and i18n?
15:42:30 <samccann> also, there are lessons we want others to be aware of. I'm just not sure it's  worth it for style guide?
15:42:38 <samccann> I guess we make the list(s) and then decide
15:43:16 <acozine> definitely worth revisiting
15:45:56 <acozine> I can't find an issue for the SEO stuff
15:46:35 <samccann> I'll try to find it.
15:48:32 <samccann> nope. can't find it either. must not have created one
15:49:35 <acozine> #action acozine and samccann to go back to SEO meeting notes and create issues as appropriate
15:50:10 <acozine> anything else?
15:50:15 <acozine> we've got ten minutes left
15:50:37 <acozine> open floor going once . . .
15:50:41 <samccann> we should also review issues or split some of them to be `easyfix`
15:50:50 <samccann> those seemed to get some fast love in the community
15:51:38 <acozine> yeah, the current list isn't very inviting: https://github.com/ansible/ansible/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Adocs+label%3Aeasyfix
15:53:52 <acozine> #action identify `easyfix` issues among the open docs issues
15:54:57 <acozine> open floor going twice . . .
15:55:57 <acozine> huh, thinking of internationalization - that's an idiom folks might not know
15:56:31 * acozine needs to turn on the part of her mind that thinks in a foreign language more often
15:56:37 <samccann> heh
15:56:59 <acozine> does anyone have anything to add before we end the meeting?
15:57:52 <acozine> thanks samccann for chatting with me . . . hope a few more folks turn up next week and the week after while I'm out of town
15:58:13 <samccann> hehe otherwise I can talk with the voices in my head for awhile :-)
15:58:18 <acozine> agenda items for next week are welcome
15:58:38 <acozine> please add them to https://github.com/ansible/community/issues/389
15:58:47 <acozine> happy summer, folks!
15:58:51 <acozine> #endmeeting