Open Stack

Thanks Tom.

On Thu, Apr 9, 2015 at 4:09 AM, Tom Fifield <tom at openstack.org> wrote:

>  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
>
>
>    1. 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
>
>
>    1. Previous statement that RST-based docs would not be published
>    without agreement on the translation toolchain was acknowledged
>
>
>    1. 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
>
>
>    1. 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
>
>
>    1. 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)
>
>
>    1. Strings that are entirely markup (eg
>    :ref:`Boot_instance_from_image_and_attach_non-bootable_volume`)
>
>
>    1. Strings that contain significant amounts of markup
>
>
>    1. Strings that contain markup characters that are unusual for
>    translations, eg backticks, asterisks
>
>
>    1. Strings that contain markup where placeholders were previously used
>
>
>    1. ... 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
>
>
>    1. 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
>
>
>    1. Daisy & Tom stated that they preferred such issues to be fixed in
>    the toolchain
>
>
>    1. 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.
>
>
>    1. 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
>
>
>    1. 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
>
>
>    1. There is an open question about whether it is possible to deliver
>    an improved i18n experience with the current toolchain
>
>
>    1. There is not yet agreement that the current documentation toolchain
>    is meeting the needs of the i18n team
>
>
>
Happy to dig into this further, and we'll work through issues before
publishing.

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.

Thanks,
Anne


>
>  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
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-i18n/attachments/20150409/128cd965/attachment.html>