Open Stack

Tom Fifield <tom at openstack.org> wrote on 2015/04/09 17:09:17:

> From: Tom Fifield <tom at openstack.org>
> To: "openstack-docs at lists.openstack.org" <openstack-
> docs at lists.openstack.org>, "openstack-i18n at lists.openstack.org"
> <openstack-i18n at lists.openstack.org>
> Date: 2015/04/09 17:09
> Subject: [Openstack-i18n] Status of the RST Documentation Toolchain
>
> 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.

I investigated the translation process of RST document, asked by Anne and
Andreas.
While I made test, I used playground-user-guide, which was a quite new
document.
I didn't pay attention to the pot content changes between the old version
and the new version.
I'm quite sorry for that.
I don't want to block anything.
In my mind, the toolchain could be improved continuously,
both before publication and after publication.

> 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-i18n mailing list
> Openstack-i18n at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-i18n/attachments/20150409/a6f4a598/attachment-0001.html>