<div dir="ltr">Thanks Tom.<br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Apr 9, 2015 at 4:09 AM, Tom Fifield <span dir="ltr"><<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000">
<div><span>Hi,</span></div>
<div><br>
</div>
<div><span>Andreas,
Daisy, Motoki-san and myself have just had an impromptu
hour-long discussion regarding the Status of the RST
Documentation Toolchain, particularly its translation
components. This meeting was spurred on by the email to the i18n
mailing list announcing the pending removal of docbook user
guides, and all present acknowledged the meeting would have been
great if it had happened sooner :) This is the brief summary!</span></div>
<div><br>
</div>
<div>
<ol start="1">
<li><span>Everyone
involved wants to make translators happy, and hopes that the
process of moving to RST can deliver an improved toolchain</span></li>
</ol>
</div>
<div>
<ol start="2">
<li><span>There
has been inadequate communication between the documentation
team and the i18n team regarding requirements and timelines
during this process and we will strive to improve this</span></li>
</ol>
</div>
<div>
<ol start="3">
<li><span>Previous
statement that RST-based docs would not be published without
agreement on the translation toolchain was acknowledged</span></li>
</ol>
</div>
<div>
<ol start="4">
<li><span>Based
on the user guide example, about 50% of existing translated
strings (1943 vs 943) need to be re-translated with the
current conversion process</span></li>
</ol>
</div>
<div>
<ol start="5">
<li><span>Noone
on the i18n team had yet the opportunity to assess the
strings produced by the RST in a fuller guide and problems
weren't picked up with </span><span>initial
version of </span><span>guides
in the playground </span><span>folder</span></li>
</ol>
</div>
<div>
<ol start="6">
<li><span>Daisy
in particular hasn't been able to log in to transifex today
to check the new user guide. We are currently using the
standard Sphinx translation tools, though, there was some
definite concern over the quality of the strings produced by
the RST, including:</span></li>
</ol>
</div>
<blockquote>
<div>
<ol start="1">
<li><span>Strings
that should have been trivially updated during conversion
from docbook without human interaction needed (eg
**string**\n)</span></li>
</ol>
</div>
</blockquote>
<blockquote>
<div>
<ol start="2">
<li><span>Strings
that are entirely markup (eg
:ref:`Boot_instance_from_image_and_attach_non-bootable_volume`)</span></li>
</ol>
</div>
</blockquote>
<blockquote>
<div>
<ol start="3">
<li><span>Strings
that contain significant amounts of markup</span></li>
</ol>
</div>
</blockquote>
<blockquote>
<div>
<ol start="4">
<li><span>Strings
that contain markup characters that are unusual for
translations, eg backticks, asterisks</span></li>
</ol>
</div>
</blockquote>
<blockquote>
<div>
<ol start="5">
<li><span>Strings
that contain markup where placeholders were previously
used</span></li>
</ol>
</div>
</blockquote>
<blockquote>
<div>
<ol start="6">
<li><span>...
this list is incomplete and comes only from what amotoki
and fifieldt saw during the meeting - the broader i18n
community has not yet been asked for feedback outside of
Andreas' recent email</span></li>
</ol>
</div>
</blockquote>
<div>
<ol start="7">
<li><span>There
is an open issue about how to fix problems like the above.</span></li>
</ol>
</div>
<blockquote>
<div>
<ol start="1">
<li><span>Andreas
stated that not maintaining our own custom scripts is a
good aim, and some of the issues above could be handled
with a one time fix at conversion time</span></li>
</ol>
</div>
</blockquote>
<blockquote>
<div>
<ol start="2">
<li><span>Daisy
& Tom stated that they preferred such issues to be
fixed in the toolchain</span></li>
</ol>
</div>
</blockquote>
<blockquote>
<div>
<ol start="3">
<li><span>Just
looking at the "** STRING **" issue, it's 70 strings but a
quick proof of concept d</span><span>idn't
result in fixing the issue - we haven't worked out why
yet.</span></li>
</ol>
</div>
</blockquote>
<blockquote>
<div>
<ol start="4">
<li><span>The
current toolchain is difficult to modify, since it relies
on an upstream component that is used by multiple
projects, meaning post processing and pre-processing are
the only real approach we have</span></li>
</ol>
</div>
</blockquote>
<blockquote>
<div>
<ol start="5">
<li><span>It
could be complicated to use post-processing and
pre-processing to implement fixes for issues beyond the
trivially updated string example in the current toolchain</span></li>
</ol>
</div>
</blockquote>
<div>
<ol start="8">
<li><span>There
is an open question about whether it is possible to deliver
an improved i18n experience with the current toolchain</span></li>
</ol>
</div>
<div>
<ol start="9">
<li><span>There
is not yet agreement that the current documentation
toolchain is meeting the needs of the i18n team</span></li>
</ol>
</div>
<div><br></div></div></blockquote><div><br></div><div>Happy to dig into this further, and we'll work through issues before publishing. </div><div><br></div><div>I have to drive four hours today so I won't be online much, but I apologize for the scramble and will continue to work with the teams. </div><div><br></div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000"><div>
</div>
<div><br>
</div>
<div><span>Based
on the meeting, and especially the fact that due to inadequate
communication the i18n team (inc Daisy) has not yet had the
opportunity to assess the RST documentation toolchain fully, I
would propose that the removal of existing guides and
publication of RST guides be delayed until that's happened.</span></div>
<div><span>We suggest
that Daisy does an initial assessment </span><span>and
arrange a meeting to discuss next steps as soon as possible</span><span>.</span><span> There
are many things we can fix with the the toolchain any time after
publication, however it is important that we assess what needs
to be done and ensure that we can actually feasibly deliver an
improved experience for our translations, as well as our doc
team.</span></div>
<div><br>
</div>
<div><br>
</div>
<div><span>Regards,</span></div>
<div><br>
</div>
<div><br>
</div>
<div><span>Tom</span></div>
<div><br>
</div>
</div>
<br>_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature">Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div></div>