Guide Versioning

[Ruediger Landmann]

On 06/24/2010 10:07 PM, Eric "Sparks" Christensen wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 06/24/2010 12:54 AM, Ruediger Landmann wrote:
>    
>> On 06/24/2010 01:04 PM, Eric "Sparks" Christensen wrote:
>>      
>>> So your release is based on localization.
>>>        
>> Pragmatically, yes.
>>
>> But it's really more that the change of state from "draft" to "we assure
>> you readers out there that this works for F14" coincides with the change
>> of state from "not ready for translation" to "ready for translation".
>>
>> However, because "ready for translation" is a harder, more visible
>> change of state (and one that impacts directly on our colleagues),
>> "ready for translation" is a really good indicator that the other change
>> of state ("this works for F14") has taken place.
>>      
> But things change...
>    

Sorry, I'm not sure what point you're making here. Hopefully, it's 
addressed below, however.

>>> So if something changes in
>>> the release after Fedora is released we really can't update the guides
>>> because it would break translations.
>>>
>>>        
>> Correct. Any string change, no matter how minor, breaks every single
>> translation of that document. We just don't have the bandwidth to
>> accommodate that.
>>
>> Obviously, if we discover a severe problem in a F13 doc (for example
>> something that tells users to do something really harmful) then we
>> actually *want* to break any translations of that; but this is where we
>> have to work closely with L10N.
>>
>> This all means that anyone can check out the source for themselves at
>> any time and build the doc in any language on which translators have
>> finished their work.
>>      
> Well, I don't think that we should be making available incorrect
> information.  If the information is wrong it should be fixed!
>
>    

If we had unlimited resources, I would of course agree with you. 
However, we have to balance removing relatively minor nits from 
documents against constantly breaking translations and shifting 
goalposts for translators. This means publishing "mostly correct" 
information.

In Fedora, we have formal documentation in multiple translations with a 
volunteer corps of translators (ie, people from whom we're asking 
volunteer time and effort every time we change something). This is not 
an agile environment.

If we care about translations, formal documentation is pretty much the 
other end of the publishing spectrum from a wiki, much closer to the 
traditional, dead-trees publishing industry (although for them, even a 
six-month turnaround is really good!)

The trade-offs here similar to the familiar engineering constraints of 
faster-better-cheaper, with the cost of making things less cheap borne 
by our translators. This also illustrates a familiar danger where people 
who make a decision aren't the same people who bear the cost of that 
decision.


>>> So does this mean we should release the F14 versions immediately
>>> following the F13 release and update the F14 regularly throughout
>>> development?
>>>
>>>        
>> Exactly the opposite.
>>
>> All development work should always take place in the "master" (Git) or
>> "trunk" (SVN) of the document and we shouldn't publish anything for F14
>> until we've had a chance to test it against the alpha.
>>      
> And this goes against our "release early, release often" 'policy'.
> Right now, under your plan, we release twice a year and have a six-month
> turn around for fixing bugs.  That's not acceptable in my opinion.
>    

I think it's all we have the bandwidth for. The other alternative is to 
do point releases of docs.

Branching to a point release is no different from branching to a new 
release. For example:

* create a new branch from "master" or "trunk" -- let's say f13.1 -- 
that contains a roll-up of a few months' worth of corrections to the 
original f13 doc
* copy all the translations from the f13 branch into the f13.1 branch
* make the f13.1 branch available in Transifex and disable the original 
f13 branch in Transifex
* the translations in the f13.1 branch eventually become the basis for 
the translations in the f14 branch

I originally planned a point release of the Fedora 12 Installation Guide 
with a series of bugfixes, but ran out of time as f13 loomed.

If you want to lower the turnaround from six months to three, then we 
all need to be preparing *right now* for a f13.1 point release for docs 
in late August or early September.

> Things change and we need to be flexible with that but if we aren't
> giving our readers a chance to properly review our new guides then we
> aren't getting the feedback we need.  If we aren't going to fix bugs
> then...  well, I'm going to fix my bugs.
>    

Of course we should fix bugs; just not in a place where we'll break 
translations.


> If we get the POT files in the hands of the translators as soon as
> possible... right now...  then they should have ample time to get the
> big stuff done which allows them to fix the smaller bugs right around
> release time.
>    

Agreed, at least in principle :) Again, this needs a point release, or 
we'll be asking  translators to work on mostly the same material in a 
f13 branch and an f14 branch. There's probably only two or three 
language teams that would not be swamped by this.

Alternatively, if any translation teams have time and effort to burn on 
docs that are still wildly subject to change, we shouldn't stand in 
their way if they want to translate the "master" or "trunk" versions of 
docs; but they would do so entirely at their own risk, and we would have 
to be quite explicit about the risks ("none of the work you do here 
might ever see the light of day").

>>> How do you handle bugs in the F13 versions?
>>>
>>>        
>> If it's a particularly severe bug, we fix it in the F13 branch, notify
>> Localization, and republish; breaking all translations in the process.
>>
>> If it's not severe, we fix it in "master" or "trunk". The fix will never
>> be published for F13, but will appear in the F14 guide (assuming that
>> the surrounding content is still relevant).
>>      
> What do you consider severe?  A bug means, usually, incorrect or
> incomplete information which sounds pretty severe to me.
>    

I don't think that all bugs are equally severe. The kinds of bugs where 
we would *want* to break translations are those that tell people to do 
things that are likely to endanger their data or the security of their 
systems. Documentation bugs of this severity are really rare; the lack 
of a warning about the changes to PackageKit in the Fedora 12 Release 
Notes springs to mind as an example.

>>>> If the guide is verified against F13 to a point where we can take the
>>>> "Draft" watermarks off it and hand it over to translators, then we can
>>>> release for F13.
>>>>
>>>>          
>>> Okay, but what if everything is good for F13 but the guide is incomplete?
>>>
>>>        
>> If we're happy to freeze development at a particular point for F13,
>> there should be no reason why we couldn't branch a mostly complete
>> document for F13, hand it over for translation, take the "draft"
>> watermark off it, and release it mid-cycle. Development then continues
>> in the "master" or "trunk" as usual. The same is true for guides not
>> completed in time for GA.
>>
>> If you don't feel that a guide is at a point where it makes sense to
>> freeze it, or where you wouldn't be happy to ask translators to put
>> their time and effort into it, this is a symptom that it's not ready for
>> release as anything but "Draft Documentation" yet.
>>
>> Cheers
>> Rudi
>>
>> PS -- one small correction; last time, I suggested that a guide
>> shouldn't be branched until Beta. While this is true in a perfect world,
>> we probably really do need to branch during Alpha so that we give
>> translators enough time to do their work. Changes in the F14 branch
>> between alpha and beta will sometimes be necessary, but as always, we
>> would try to avoid changing existing strings wherever possible. Note
>> that we need to make changes during alpha and beta in two places:
>> "master" and F14. This is where "git cherry-pick" comes in very handy.
>>      
> I really don't like freezing the guides...
>    

It's the cost of providing a stable base for translation. If we didn't 
care about any language other than English, we could (and indeed, 
should!) publish an update to a guides as soon as possible after a bug 
is raised.

If we want a more agile model, then we could certainly choose not to 
worry about providing that stable base. However, in that case we should 
certainly be up-front about that and tell Localization that we won't be 
trying to provide that any longer.