Documentation proposal

[Jannis Pohlmann]

On Mon, 04 May 2009 14:09:31 -0700
"Brian J. Tarricone" <bjt23 at cornell.edu> wrote:

> Mike Massonnet wrote:
> > 2009/5/4 Brian J. Tarricone <bjt23 at cornell.edu>:
> >> Related to synchronisation, the main benefit is that it's easier
> >> to tell what's changed -- that is, if I go and change one sentence
> >> in the English docs, rebuilding the .po files will make it very
> >> easy for the translator to figure out what I changed without
> >> having to read through the entire doc.
> > 
> > Sync the doc allows it to be mixed with english texts. Figuring that
> > syncing the translated doc is not possible, one good way would be to
> > have a trunk/ that is an in-progress documentation and english-only.
> > Than existing branches would exist for stable docs for specific
> > versions of the components and are freezed, and those would be
> > allowed to contain translations.

Branches are alternative versions of a package. That's not what we
want. We don't want xfce4-docs-en, xfce4-docs-fr etc. Distributions may
want to do that but we don't. We want xfce4-docs to include all
translated docs we have. 

I'd favor good communication and a pre-release documentation deadline
in order to make syncing doc translations before a release easier.

> I hesitate to weigh in with too strong an opinion here, since I've
> never translated anything in my life, but I'll throw this out anyway:
> this just seems counterintuitive to me.
> 
> For the translation of strings in a program, .po files seem to be a
> good choice to me.  Most UI strings are short and standalone[1], and
> are often repeated (so having one translation for all the repeats is
> a good thing).
> 
> For documentation, the work to be translated is the *entire work*. 
> Context is *everything* here, and breaking up the text into smaller 
> sections to be translated might make you *feel* like it's easier to 
> translate ("oh, I can do a little bit here, a little bit there, and
> not all at once"), but in reality, it seems like the .po file model
> would result in a lower-quality translation than just taking the
> document as a whole and translating it.

Right. That's what I've been trying to express with my earlier mails. I
think it's also more fun to translate the text as a whole. IMHO it's
also more fun to translate something with simple/easy markup rather
than having to deal with a the ridiculous markup overhead of XML.

One can still split up the translation work into smaller chunks, e.g.
by translating one manual (or one reST file) at a time.

> > It is easy to let the translator know which documentations can be
> > translated. I guess that's the best option I can come up with, that
> > is easy and doesn't let the doc being provided with different
> > locales while most of them could be out of sync. Very very annoying.
> >
> 
> Frankly this seems like the *worst* reason to use a translation
> system. If making the docs discoverable is a problem, there are much
> better ways to solve it than picking a translation model that lumps
> the docs translations in with the rest of the normal translator's
> workflow.
> 
> >> How do translators deal with the website translations?  Does that
> >> seem to work well?  Maybe we should use that as a model?
> > 
> > The website, well a pita of course.
> 
> Ah, that's a shame.  Pass on that model, then ^_~.

IMHO that's mainly due to the repository being somewhat "secret" (as in
not really well-known) but most importantly, because of the
enormous markup overhead of HTML. You can also very easily break the
website if you change the markup or PHP code in the files to be
translated. 

> Also as a bit of a semi-unrelated aside... I wonder if we're doing
> the right thing in trying to push docs translation on our existing
> group of translators.  For some of them, sure, it's fine, but
> translating UI strings and translating documentation prose requires a
> bit of a different language skill set.  (In a similar way, writing
> English UI strings requires a different language skill set than
> writing English docs.)  Of course, we don't want to turn down help,
> especially if help is otherwise unavailable...

Again, I've been trying to express the same thing when I wrote about
"dedicated translators". Looking back at the past years it's
unrealistic that the docs translation coverage will become as good as
that of our libraries and applications, simply because it is a lot of
work. The risk of getting out of sync in translated versions is high,
no matter how we handle translations.

  - Jannis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://mail.xfce.org/pipermail/xfce4-dev/attachments/20090505/acc170c7/attachment.pgp>