Re: Nine Months in Six Months

["Gustavo J. A. M. Carneiro" <gjc inescporto pt>]

S� 2006-09-09 �04:55 +0200, BJ�Lindqvist escreveu:
> On 9/8/06, Don Scorgie <DonScorgie blueyonder co uk> wrote:
> > Doc people do not have enough time.  Its as simple as that.  As shaunm
> > pointed out, this release we got 4 weeks to update the documentation.
> > This included 3 new modules needing docs, as well as lots of updates to
> > lots of other docs.  The doc team has been on skeleton staff ever since
> > I've known it.  Most of the docs are now pretty out of date.  Add in a
> > desire to have translated docs and basically, the doc team has negative
> > time to do the required work.  The great part about it is that for the
> > other 5 months, the doc team is pretty much sitting around, twiddling
> > thumbs and thinking up plans for world domination [1].  The writers
> > can't really do their thing with a moving target.
> 
> Then lets stop the target! If I understand you correctly, the
> development process from the documentors point of view is kind of like
> this.
> 
> * Five months were developers play and pretty much destroy all the docs we make.
> * Four weeks were we can undo the damage caused and make GNOME understandable.
> 
> Maybe this problem can be solved by elevating the documentations and
> the translations status in the project? For example, patches are very
> seldom accepted if they introduce regressions in the software. But
> regressions in the docs aren't counted in the same way. New code very
> often changes applications behaviour so that the manual becomes
> invalid. What if the documentation and translation regressions were
> counted in the same way as code regressions?
> 
> To me, that makes sense. An untranslated string is just as annoying as
> a frequently segfaulting program. So lets treat the problems the same.
> Code that changes behaviour shouldn't be committed unless the
> documentation is updated. User visible strings shouldn't be changed
> unless the translations are updated. Something like that?

  1. Code truly is more important than documentation, that's why it's
treated more importantly;

  2. If you raise the bar for accepting contributions, making
contributors update documentation at the same time, you'll surely have
less contributions;

  3. Documention doesn't destabilize the program, it can go on for a
much longer time after code/feature freeze.  If you want to delay the
official GNOME .0 release for documentation, that's another matter.  But
delaying or forbidding contributions because of lack documentation is
unthinkable.

-- 
Gustavo J. A. M. Carneiro
<gjc inescporto pt> <gustavo users sourceforge net>
The universe is always one step beyond logic