
<html><body>

<p><tt><font size="2">Tom Fifield <tom@openstack.org> wrote on 2015/04/09 17:09:17:<br>

<br>

> From: Tom Fifield <tom@openstack.org></font></tt><br>

<tt><font size="2">> To: "openstack-docs@lists.openstack.org" <openstack-<br>

> docs@lists.openstack.org>, "openstack-i18n@lists.openstack.org" <br>

> <openstack-i18n@lists.openstack.org></font></tt><br>

<tt><font size="2">> Date: 2015/04/09 17:09</font></tt><br>

<tt><font size="2">> Subject: [Openstack-i18n] Status of the RST Documentation Toolchain</font></tt><br>

<tt><font size="2">> <br>

> Hi,</font></tt><br>

<tt><font size="2">> <br>

> Andreas, Daisy, Motoki-san and myself have just had an impromptu <br>

> hour-long discussion regarding the Status of the RST Documentation <br>

> Toolchain, particularly its translation components. This meeting was<br>

> spurred on by the email to the i18n mailing list announcing the <br>

> pending removal of docbook user guides, and all present acknowledged<br>

> the meeting would have been great if it had happened sooner :) This <br>

> is the brief summary!</font></tt><br>

<tt><font size="2">> <br>

> 1. Everyone involved wants to make translators happy, and hopes that<br>

> the process of moving to RST can deliver an improved toolchain</font></tt><br>

<tt><font size="2">> 2. There has been inadequate communication between the documentation<br>

> team and the i18n team regarding requirements and timelines during <br>

> this process and we will strive to improve this</font></tt><br>

<tt><font size="2">> 3. Previous statement that RST-based docs would not be published <br>

> without agreement on the translation toolchain was acknowledged</font></tt><br>

<tt><font size="2">> 4. Based on the user guide example, about 50% of existing translated<br>

> strings (1943 vs 943) need to be re-translated with the current <br>

> conversion process</font></tt><br>

<tt><font size="2">> 5. Noone on the i18n team had yet the opportunity to assess the <br>

> strings produced by the RST in a fuller guide and problems weren't <br>

> picked up with initial version of guides in the playground folder</font></tt><br>

<tt><font size="2">> 6. Daisy in particular hasn't been able to log in to transifex today<br>

> to check the new user guide. We are currently using the standard <br>

> Sphinx translation tools, though, there was some definite concern <br>

> over the quality of the strings produced by the RST, including:</font></tt><br>

<tt><font size="2">> 1. Strings that should have been trivially updated during conversion<br>

> from docbook without human interaction needed (eg **string**\n)</font></tt><br>

<tt><font size="2">> 2. Strings that are entirely markup (eg <br>

> :ref:`Boot_instance_from_image_and_attach_non-bootable_volume`)</font></tt><br>

<tt><font size="2">> 3. Strings that contain significant amounts of markup</font></tt><br>

<tt><font size="2">> 4. Strings that contain markup characters that are unusual for <br>

> translations, eg backticks, asterisks</font></tt><br>

<tt><font size="2">> 5. Strings that contain markup where placeholders were previously used</font></tt><br>

<tt><font size="2">> 6. ... this list is incomplete and comes only from what amotoki and <br>

> fifieldt saw during the meeting - the broader i18n community has not<br>

> yet been asked for feedback outside of Andreas' recent email</font></tt><br>

<tt><font size="2">> 7. There is an open issue about how to fix problems like the above.</font></tt><br>

<tt><font size="2">> 1. Andreas stated that not maintaining our own custom scripts is a <br>

> good aim, and some of the issues above could be handled with a one <br>

> time fix at conversion time</font></tt><br>

<tt><font size="2">> 2. Daisy & Tom stated that they preferred such issues to be fixed in<br>

> the toolchain</font></tt><br>

<tt><font size="2">> 3. Just looking at the "** STRING **" issue, it's 70 strings but a <br>

> quick proof of concept didn't result in fixing the issue - we <br>

> haven't worked out why yet.</font></tt><br>

<tt><font size="2">> 4. The current toolchain is difficult to modify, since it relies on <br>

> an upstream component that is used by multiple projects, meaning <br>

> post processing and pre-processing are the only real approach we have</font></tt><br>

<tt><font size="2">> 5. It could be complicated to use post-processing and pre-processing<br>

> to implement fixes for issues beyond the trivially updated string <br>

> example in the current toolchain</font></tt><br>

<tt><font size="2">> 8. There is an open question about whether it is possible to deliver<br>

> an improved i18n experience with the current toolchain</font></tt><br>

<tt><font size="2">> 9. There is not yet agreement that the current documentation <br>

> toolchain is meeting the needs of the i18n team</font></tt><br>

<tt><font size="2">> <br>

> Based on the meeting, and especially the fact that due to inadequate<br>

> communication the i18n team (inc Daisy) has not yet had the <br>

> opportunity to assess the RST documentation toolchain fully, I would<br>

> propose that the removal of existing guides and publication of RST <br>

> guides be delayed until that's happened.</font></tt><br>

<br>

<tt><font size="2">I investigated the translation process of RST document, asked by Anne and Andreas.</font></tt><br>

<tt><font size="2">While I made test, I used playground-user-guide, which was a quite new document.</font></tt><br>

<tt><font size="2">I didn't pay attention to the pot content changes between the old version and the new version.</font></tt><br>

<tt><font size="2">I'm quite sorry for that.</font></tt><br>

<tt><font size="2">I don't want to block anything.</font></tt><br>

<tt><font size="2">In my mind, the toolchain could be improved continuously, </font></tt><br>

<tt><font size="2">both before publication and after publication.</font></tt><br>

<br>

<tt><font size="2">> We suggest that Daisy does an initial assessment and arrange a <br>

> meeting to discuss next steps as soon as possible. There are many <br>

> things we can fix with the the toolchain any time after publication,<br>

> however it is important that we assess what needs to be done and <br>

> ensure that we can actually feasibly deliver an improved experience <br>

> for our translations, as well as our doc team.</font></tt><br>

<tt><font size="2">> <br>

> Regards,</font></tt><br>

<tt><font size="2">> <br>

> Tom</font></tt><br>

<tt><font size="2">> _______________________________________________<br>

> Openstack-i18n mailing list<br>

> Openstack-i18n@lists.openstack.org<br>

> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n</a><br>

</font></tt></body></html>