Re: Improving things for translators

[Shaun McCance <shaunm gnome org>]

On Fri, 2008-03-14 at 22:53 +0100, Claude Paroz wrote:
> Le vendredi 14 mars 2008 à 16:12 -0500, Shaun McCance a écrit :
> > Indeed.  Documentation writing doesn't really heat up
> > until after the feature freeze, which is roughly half
> > way through our release cycle.  That leaves the team
> > three months to update all the documentation.  Factor
> > in these facts:
> > 
> > 1) Our documentation is out of date, sometimes by as
> > much as a few years.  We're still trying to clear the
> > backlog, so to speak, which makes for an even heavier
> > workload.  If we ever caught up, we'd be in a better
> > position to make future updates in a timely manner.
> > 
> > 2) The desktop release contains 86 documents.  Some
> > of them are smallish, but some of them are huge.  We
> > add new modules with every release.
> > 
> > 3) We have almost no active writers at the moment.
> > Virtually all updates are those that Ubuntu sends
> > upstream.  I'm way too busy being a hacker to be
> > a writer.
> > 
> > My long-standing policy on documentation freezes is
> > that it's something we want to do at some point, but
> > we're not in a position to do it right now.  We need
> > every last second we can get to do documentation.
> 
> Hi Shaun,
> 
> I'm convinced that a 3 day-freeze in a six months release won't change
> anything to the current lack of writers for docs. It's just a timing
> matter.
> 
> As a translator, what I would absolutely prevent, it's what happened
> with the platform-overview document (excellent, by the way!) you updated
> some minutes/hours before releasing. We worked many hours on the
> translation of this document, Vincent and I, just to see it being only
> partially translated in GNOME 2.22 :-(
> If a freeze would have been in place, you probably would have planned to
> update the doc three days before. Don't take it as a personal attack,
> you had the right to do it that way.

Honestly, I don't think I would have.  I would have
simply waited for the 2.22.1 release.  I (co-)maintain
four modules and I'm the de facto maintainer of 70+
individual documents.  No amount of planning would
make me able to finish everything on time.

I'm very sorry that your hard work didn't result
in a 100% translated document, and that there was
really no way you could have fixed that.  (That
goes for Jorge as well; Spanish was also at 100%
before my changes.)

But I believe the changes had a net positive impact
on the total readership.  French and Spanish were
the only two translations that would have been 100%,
which means that a huge percentage of our readers
will be reading in English.  Having the information
correct, in this case, was more important.

> > What I would prefer to do, at least initially, is to
> > implement voluntary freezes on documentation.
> 
> Sorry, but a voluntary freeze means nothing to me. Either a normal
> freeze or nothing.

I don't understand this.  Frankly, I think voluntary
freezes are a good idea, even if we have mandatory
freezes as well.  If we have a mandatory freeze three
days before release, but I voluntarily freeze a week
before, that's four extra days you can translate with
a reasonable assurance that your work won't be wasted.

We will never be able to have documentation freezes
coincide with string freezes.  Documentation provides
orders of magnitude more total content to translate.
It is virtually impossible for you to finish with a
three day window.

> >   With
> > Pulse (cue dramatic music) we could extract various
> > bits of metadata about status, reviews, and readiness
> > for translation from our documents.  Then translators
> > could look at Pulse to see which documents are worth
> > devoting time to, and which are going to change out
> > from underneath them.  Whenever we finish a document
> > (cue laughter), we'd mark it as such, and translators
> > would know.
> 
> Damned-lies already produces stats about new strings to translate. And
> we can assume that new strings committed in SVN means they are worth to
> be translated also. OK, it may also be work in progress, but in this
> special case, a simple mail to gnome-i18n will do the job.

Like the documentation team, many translation teams are
behind.  They have a backlog, and they have to catch up.
So say there was a paragraph added in 2.18.  The Afrikaans
team gets to the point where they're ready to translate
documentation.  It's not a new paragraph in 2.24, so it's
not safe to assume, as in your example, that it's ready
to be translated.

Honestly, whether the translation teams want to look at
documentation status or not, I will be adding it to Pulse.
The documentation team needs to know where things stand
in order to prioritize their efforts.  It's in your best
interest to prioritize documents that are marked final.

> > Having fully translated documentation is of no use if
> > what was translated was crap to begin with.  Garbage
> > in, garbage out.
> 
> Of course, but we can say the same for programs. That doesn't prevent in
> any way to put a freeze in place for UI translations.

I don't think that's comparable.  Excepting spelling and
grammar errors, the strings in an application are correct
by definition.  They might be poorly worded, but they are
what they are.

Documentation doesn't exist on its own.  It chases the
applications.  If the documentation talks about some
feature or string or interface element that no longer
exists, it's not just poorly worded.  It's wrong.

Incorrect content is not helpful.  In fact, it's often
less helpful than no content at all.  Incorrect content
in your own language is no more helpful than incorrect
content in another language.

--
Shaun