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