Thanks Tom. On Thu, Apr 9, 2015 at 4:09 AM, Tom Fifield <tom@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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
-- Anne Gentle annegentle@justwriteclick.com