2 Replies Latest reply: Sep 20, 2011 6:13 AM by Hardy Ferentschik RSS

Workflow questions

Hardy Ferentschik Novice

Hi,

 

I have several questions regarding the workflow. Maybe someone can help me clarifying them :-)

Here is the workflow again:

 

  1. Author modifies documentation, checks in DocBook XML source.
  2. Documentation freeze is announced.
  3. Run import job (eg from a CI platform like Jenkins). (See script zanata_import_source.)
  4. Translators start translating the imported DocBook using Zanata.
  5. Run automated nightly builds using Jenkins. (See script zanata_draft_build)
  6. If author changes any XML, reimport changes by returning to Step 3.
  7. Translation Freeze announced, and Zanata translations declared "final".
  8. Run Documentation Release build. (See script zanata_export_translations)

 

First question I have is regarding point 2 and 6. Does it make sense to already start translating the documentation while development occurs and you know that the documentation will (at least partly) still change? Or do you really need a documentation freeze?How well can this translation process (or the pot/po file approach in general) deal with changes in pot files? Does anyone have experience with this?

 

My second question is about the documentation release. Assuming I do a documentation freeze, how do I handle the documetation release build in relation to the source code. At the moment I am ready for a documentation freeze I am probably also going to release my new project version (say 1.0). This version will the tagged in the version control system. Some time later the translations are complete on zanata and I want to do a documentation release. At this point I probably want to check in the translations into version control. The question is where? I cannot change the tag and just add the documentation to the 1.0 tag. What are the best practices around this?

  • 1. Re: Workflow questions
    Sean Flanigan Newbie

    Hardy Ferentschik wrote:

     

    Hi,

     

    I have several questions regarding the workflow. Maybe someone can help me clarifying them :-)

    Here is the workflow again:

     

    1. Author modifies documentation, checks in DocBook XML source.
    2. Documentation freeze is announced.
    3. Run import job (eg from a CI platform like Jenkins). (See script zanata_import_source.)
    4. Translators start translating the imported DocBook using Zanata.
    5. Run automated nightly builds using Jenkins. (See script zanata_draft_build)
    6. If author changes any XML, reimport changes by returning to Step 3.
    7. Translation Freeze announced, and Zanata translations declared "final".
    8. Run Documentation Release build. (See script zanata_export_translations)

     

    First question I have is regarding point 2 and 6. Does it make sense to already start translating the documentation while development occurs and you know that the documentation will (at least partly) still change? Or do you really need a documentation freeze?How well can this translation process (or the pot/po file approach in general) deal with changes in pot files? Does anyone have experience with this?

     

    My second question is about the documentation release. Assuming I do a documentation freeze, how do I handle the documetation release build in relation to the source code. At the moment I am ready for a documentation freeze I am probably also going to release my new project version (say 1.0). This version will the tagged in the version control system. Some time later the translations are complete on zanata and I want to do a documentation release. At this point I probably want to check in the translations into version control. The question is where? I cannot change the tag and just add the documentation to the 1.0 tag. What are the best practices around this?

    First question:

    This is only one suggestion for a workflow; feel free to adapt for your project. It's about minimising the amount of re-translation. If you simply add content, there should be no problem. But modifying existing text which has already been translated may lead to extra work. Also, if a source file is renamed, translators will have to go through the new file and look for Translation Memory matches and copy them in.

     

    A documentation freeze is just a way of letting translators know that it's safe to start work. As long as the author and the translators are communicating, you can co-ordinate any way you like.  (eg "I've finished Chapter One, translations welcome").

     

    Second question:

    Perhaps you could just have a tag "docs-1.0-en" for the English documentation freeze and a second tag "docs-1.0" for the finalised translations? (Or "project-1.0-docs-en" and "project-1.0-docs" if that fits better.)

     

    I'll ask someone from our L10n team to chime in.

  • 2. Re: Workflow questions
    Hardy Ferentschik Novice

    Sean Flanigan wrote:

     

    Perhaps you could just have a tag "docs-1.0-en" for the English documentation freeze and a second tag "docs-1.0" for the finalised translations? (Or "project-1.0-docs-en" and "project-1.0-docs" if that fits better.)

     

    Right, versioning the docs independently could be one approach. That makes building a combined distro package very hard though, but maybe there is no easy solution for this.

    I'll ask someone from our L10n team to chime in.

    That would be awesome.