dhis2-documenters team mailing list archive

[Knut Staring <knutst@xxxxxxxxx>]

Thanks a lot Jason. Comments below.

On Tue, Sep 7, 2010 at 6:32 AM, Jason Pickering
<jason.p.pickering@xxxxxxxxx> wrote:
> Hi Knut,
> Thanks for your efforts on this. I am reluctant to move the source
> just yet. I think we need to think through the translation workflow a
> bit better, and not introduce too many changes at once. We have seen a
> few more commits from others, which is a good thing, but of course,
> getting involved in the documentation effort is still pretty
> complicated with bzr, DocBook, etc. Introducing more tools like PO and
> moving the source and images out of launchpad may just complicate
> things. Lets try and keep it as simple as possible, without too many
> complications.

I agree very much with keeping things simple. To me, introducing PO is
not an additional step to an already complicated process, but a way to
allow translators to bypass the whole process: They don't have to get
involved with Maven, Bazaar, or Serna or XML, just POedit.
This means that someone else will have to handle the structure of the
document and checking in translations, but I think that is a lot
easier than providing remote support to people who are not using the
above tools on a regular basis. So basically I suggest email and
POedit as the only tools needed, which I think will vastly enlarge the
pool of possible collaborators.

> Firstly, I have removed all the revisions up until 214, which I think
> is where all the commit related to multilingual documents started.

Thanks, that was needed.

> Going forward I would suggest that we fork each language branch, into
> a seperate tree, in order to cut down on the size of the individual
> branches. My suggestion is that each language be placed in a seperate
> tree, that is branched from the main English documentation. This seems
> to make sense to me, as most people will not need every language, but
> would be more interested on working on a particular language.

I agree that most people only need one language and perhaps English
and that the size of the screenshots means some kind of splitting up,
so people don't have to download hundreds of MB. There is also merit
to allowing each language community to manage their own documentation
needs, as the VN team has already done by introducing their own
filenames and structure.

However, in my opinion, we need to think along the lines of the HISP
concept of minimal common dataset, and concentrate on a common core of
documentation with a unified structure. Any changes for a particular
language should be as addition. There are two main reasons for this -
inline help in the DHIS2 application, and the need to manage the
overall translation process.

We now need a system for multiple languages in
dhis-2\dhis-services\dhis-service-options\src\main\resources, e.g.
help_content.en.xml, help_content.fr.xml etc. And then of course the
right one must be chosen according to the user GUI setting.

For this to work well, we need to maintain exactly the same structure
for all languages. This means that we only maintain one set of Docbook
 files, namely for English. Whenever structural changes need to be
made, they should be made in these master XML files. For the other
languages, we only need PO files with translations. A first set of PO
files can be generated using Google Translate, but then must be turned
over to translators (with POedit as the only tool).

So English remains the master language, which I think is only
realistic, looking at the project. And it will be easy to point people
to the right documentation without even knowing a language. Thus we
should not fork the text at all (it doesn't get very big anyway), but
keep it all in the current structure. Instead, we should remove the
/images folder and check it into a separate branch. If people want to
create separate screenshots for other languages such as French, these
should be in yet another branch. Alternatively, we could place all
screenshots on another server for download, outside of version
control.

This means a minimal adjustment to what we currently have (just moving
the images), but of course the instructions for building must explain
exactly what to do with the images. It could of course be possible to
script this also, though not sure it is worth the effort.

> So, for
> instance to fork the current branch you would do this..
>
> 1) Fork the branch. bzr branch
> lp:~dhis2-documenters/dhis2/dhis2-docbook-docs dhis2-docbooks-docs-fr
> 2) Make all the necessary changes that are required. Transform the XML
> to PO files, machine translate it, revise the PO files, transform back
> to XML, and modify the pom.xml file to suit your needs.
> 3) Push the changes back to launchpad in a new branch "bzr push
> lp:~dhis2-documenters/dhis2/dhis2-docbook-docs-fr/"
>
> I have followed this workflow, and create this new branch.
>
> I think this should be a more sustainable workflow and hopefully (with
> more careful) management of the images, keep the size of the branches
> down to a reasonable size. I think it will also help to encourage
> ownership of each language. People would be free to translate back and
> forth from each branch, but I assume for the time being, most stuff
> would be translated from English into other languages.
>
> Also, using the command bzr checkout --lightweight
> lp:~dhis2-documenters/dhis2/dhis2-docbook-docs   will only pull the
> latest revision

This is very useful to know, and should be highlighted on dhis2.org
and in the documentation. It would be good to have a bit more bazaar
commands in the docs.

Knut

> but not all the history, which would not be entirely
> necessary when creating a fork for a given language from the latest
> English version.  This should cut down a lot on the amount of data
> that needs to be transferred.
>
> If this sounds acceptable to everyone, I can write this up in the
> Documentation guide.
>
> Best regards,
> Jason
>
>
>
>
> On Mon, Sep 6, 2010 at 6:41 PM, Knut Staring <knutst@xxxxxxxxx> wrote:
>> Hello,
>>
>> Because of some huge commits of images from me, the documentation
>> branch in Bazaar has become almost unusable for people on slow lines,
>> as it now is 168MB to check out.
>>
>> We are therefore planning to create new branches, either in
>> Launchpad/Bazaar or in Google Code/Subversion.
>>
>> Knut
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~dhis2-devs
>> Post to     : dhis2-devs@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~dhis2-devs
>> More help   : https://help.launchpad.net/ListHelp
>>
>
>
>
> --
> Jason P. Pickering
> email: jason.p.pickering@xxxxxxxxx
> tel:+17069260025
> sip:jason.p.pickering@xxxxxxxxx
>



-- 
Cheers,
Knut Staring