Guide Translations versus Bug Fixes

[Nathan Thomas]

On 26/06/10 00:38, Ruediger Landmann wrote:
> 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.
>
>   

But Rudi, is the situation described in your footnote any worse than
having a procedure that is 100% readable but where step 4 is incorrect?

I would like to hear the thoughts of the localisation teams on this
issue. How do they feel about their current workload? Would point
releases be feasible for them?

I would also like to know roughly how many bugs we would likely to be
fixing mid-cycle - do we have any statistics for the numbers of errors
found in published guides for each cycle, so we can estimate what the
workload is likely to be?


Regards,
Nathan