[Openstack-i18n] Status of the RST Documentation Toolchain

Tom Fifield tom at openstack.org
Thu Apr 9 09:09:17 UTC 2015


Hi,

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!

 1. Everyone involved wants to make translators happy, and hopes that
    the process of moving to RST can deliver an improved toolchain

 2. 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

 3. Previous statement that RST-based docs would not be published
    without agreement on the translation toolchain was acknowledged

 4. 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

 5. 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 initial version of guides in the playground folder

 6. 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:

     1. Strings that should have been trivially updated during
        conversion from docbook without human interaction needed (eg
        **string**\n)

     2. Strings that are entirely markup (eg
        :ref:`Boot_instance_from_image_and_attach_non-bootable_volume`)

     3. Strings that contain significant amounts of markup

     4. Strings that contain markup characters that are unusual for
        translations, eg backticks, asterisks

     5. Strings that contain markup where placeholders were previously used

     6. ... 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

 7. There is an open issue about how to fix problems like the above.

     1. 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

     2. Daisy & Tom stated that they preferred such issues to be fixed
        in the toolchain

     3. Just looking at the "** STRING **" issue, it's 70 strings but a
        quick proof of concept didn't result in fixing the issue - we
        haven't worked out why yet.

     4. 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

     5. 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

 8. There is an open question about whether it is possible to deliver an
    improved i18n experience with the current toolchain

 9. There is not yet agreement that the current documentation toolchain
    is meeting the needs of the i18n team



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.
We suggest that Daisy does an initial assessment and arrange a meeting
to discuss next steps as soon as possible.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.


Regards,


Tom

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-i18n/attachments/20150409/a13cdb2e/attachment-0001.html>


More information about the Openstack-i18n mailing list