Re: documentation translation

[John Mandereau]

Han-Wen Nienhuys wrote:
> John Mandereau escreveu:
> > It's important to have the same html filenames, but the node names
> > should be translated, otherwise all that hard translation work is not
> > very worthy imho.
> 
> I don't understand  (bear with me , I haven't had a look at the 
> infrastructure for translation at all), but wouldn't the easiest 
> solution be to simply write a manual from scratch, and where applicable 
> have some sort of special command
> 
>    @node Primeiras etapas
>    @section Primeiras etapas
> 
>    INCLUDE_NODE(first steps)
> 
> which would include the contetns from First_steps.html from the english 
> manual into the Primeiras_etapas.html of the portuguese manual?

Do you mean that Primeiras_etapas.html would contain Portuguese text,
then the English version below on the same page? IMHO a link "Other
languages: English ..." like on lilypond.org main site would be cleaner.


> This would largely disconnect both manuals, which makes development 
> easier. Then, as the both manuals develop, more and more sections are 
> translated. This does not guarantee that both manuals have the same 
> structure, but that may also be a good thing, as it will give new ideas 
> and insights into  structuring the manual.

Connecting both manuals with the same node names don't forbid the
translators to create new ones, or to translate with some distance from
the English docs. 

> Of course, making this work in the PDF version is more difficult. Is a 
> bilingual PDF a goal?

It's not worth brain surgery, a translated user manual PDF can wait for
the time when the whole user manual is translated.



> Also, having two disparate documents will not work too well with content 
> negotiation, but is that a priority at this point?

Content negociation is so transparent for the end user that it's worth
using it, at the cost of using a PO file to translate the node names in
the generated HTML docs.


> I think the biggest problem now is that we have to encourage work write 
> on translating the manual, rather than integrating it with the english one.

Integrating the translated manual with the English one is mainly a
developers' issue, and it shouldn't prevent us from going on
translation. Anyway, because translating (or rewriting from scratch) a
user manual is so long (I'd say between 2 and 6 months) that it's ebtter
to technically make possible close integration between languages, so
French readers will easily be able to fall back to English docs for
untranslated stuff.

Now is the time to go on working on a straightforward translation of the
user manual in the coming months, but it doesn't prevent us from
diverging from the English docs when we have a different view of
documenting a particular topic, and give Graham feedback so he is able
to apply our ideas to the English docs if he likes. Of course, we should
clearly make the distinction between plain translated stuff and
French-only stuff.

A number of French users have created a page or a section about Lily on
their personal sites, sometimes with briliant ideas and words explaining
what LilyPond is and does. That's great and bad at the same time. It's
great because this work is independent from the LilyPond team, and
therefore berings more different points of view; and it's bad because it
certainly doesn't have the audience of lilypond.org. It might be worth
encouraging these authors to contribute to the French docs, and/or
creating a "Planet LilyPond" page listing links to these sites. As
Graham has already pointed oLe vendredi 03 novembre 2006 à 00:57 +0100,
ut, the second alternative would encourage a great number of sources of
information, and cluttered information is less efficient for the user.
The first alternative should ideally be a compromise between unified
documentation and freedom of contribution.

I don't mean you're not free to contribute to English docs today, but
when looking at the developers/users requesting help/doc
contributors/supporters repartition on the mailing lists, there seems to
be more potential contributors to the docs in the French-speaking world
than in the English-speaking world (please correct me if I'm wrong).

Cheers,
-- 
John Mandereau <address@hidden>