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. -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
