Guide Translations versus Bug Fixes

[Ruediger Landmann]

On 06/25/2010 10:31 PM, Eric "Sparks" Christensen wrote:
> For clarity I'm starting a new threat specific to the translation versus
> bug issue.
>
> The problem, as I see it, is in the guide life cycle:
>
> Development
> Development freeze
> Release POTs so translators can do their magic
> Incorporate magic in with the master source
> Compile and create all documents
> Publish
> Accept bugs
> System falls apart
>
> It's that last portion that is the problem.  If we fix the bugs then we
> break the translations which means the translators have more catch-up
> work to do.

The last step here is not accurate. The lifecycle looks more like this:

Development
Development freeze <-- NB -- not restricted to new Fedora
Release POTs so translators can do their magic
Incorporate magic in with the master source
Compile and create all documents
Publish
Accept bugs
Incorporate fixes into subsequent releases <-- NB -- not restricted to 
new Fedora

This lifecycle also misses an important exception with regard to bugs; 
which is that severe bugs trump this cycle.


> If we don't fix the bugs then we have "official"
> documentation that has known errors which, to the end user, can be
> confusing at best, catastrophic at worst.
>    

Again, not exactly true. Anything catastrophic needs to be addressed 
immediately as an exception to *any* other process that we have in place.

You'd be hard-pressed to find any piece of documentation for any product 
that isn't confusing to some end user somewhere. Errors with low 
probability of hitting people (and low impact if they do) don't need to 
be fixed immediately, any more than small bugs in software need to be 
fixed immediately.


> And apparently we aren't the only group to have this problem.  GNOME and
> Ubuntu both have this problem and address it similarly to us.
>
>    

Because they're similar projects operating under similar constraints, 
this is not surprising. I don't think we've all ended up in the same 
place by accident.

Which brings me back to my point from last time that the publication 
process for formal documentation is much more like the book publishing 
industry than it is like a wiki.


> It seems that we have two choices:
>
> 1) Fix the bugs, push the enhancements to the next release, and
> translators have more work to do although we should be able to minimize
> the work.
>
> 2) Roll all the bugs and enhancements to the next release and do zero
> maintenance to the documentation once they have been published.
>    

I think this is a false choice, if only because it conflates Fedora 
releases with documentation releases.

We *must* run through that lifecycle at the top of this post at least 
once per Fedora release so that we have a documentation suite available 
for new releases of Fedora at GA.

However, there's no reason why we must *only* run through that lifecycle 
once per Fedora release --  guide leads can do as many documentation 
point releases as they feel necessary through the lifetime of their 
guides. Branching for a documentation point release isn't exactly hard, 
as I outlined in my previous post.


> Personally, I lean more towards the first option.  As Shaun, from GNOME,
> said last night, "...I don't think fully translated docs are worthwhile
> if they're wrong".
>    

This is only true for some values of "wrong" and some values of 
"worthwhile".

A fully-translated guide that accurately documents 90% of the procedures 
that 90% of users are ever going to perform is indeed "worthwhile" to 
most of those users most of the time.

And of course, for the same values of "wrong" and "worthwhile" you can 
just as easily and truthfully say "...I don't think docs that are not 
wrong anywhere are worthwhile if they're not fully translated into a 
language that I can read".[0]


> And we should be able to limit the amount of errors that get translated
> in the first place by actually doing QA.
>    

Agreed. In subsequent cycles, we really need to be making much more 
noise during the Alpha phase to get more eyes onto our drafts. I think 
we did a better job of that for F11 and F12 than we did of F13, but I 
think that was largely due to drafts from RH-led docs only becoming 
available so comparatively late for F13.

Cheers

Rudi


[0] and don't underestimate the importance of "fully". Consider a 
procedure described in documentation that's 100% correct but where step 
4 is in a language that you can't read.