Re: Nine Months in Six Months

[Shaun McCance <shaunm gnome org>]

On Sat, 2006-09-09 at 09:41 +0400, Nickolay V. Shmyrev wrote:
> В Сбт, 09/09/2006 в 04:55 +0200, BJörn Lindqvist пишет:
> > 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?
> > 
> 
> Exactly, and although it's a not reasonable to wait for translations
> update as Adam pointed, C locale documentation should be updated by
> change author. As for translations we don't have much problem with them
> now, when we support more than 40 languages.

You'll notice one of the new things in my proposal
was the idea of a string review.  There are a lot
of crappy strings in our interfaces, often because
many of our programmers just don't have very good
English skills.

And that's fine.  Hey, my German pretty much sucks,
although I can get by with it.  I can't expect the
world to have perfect English.  So we'll do some
string reviews instead, where we can fix problems.

But now you want all these programmers to assemble
their documentation piecemeal as they add features?

Even if they all had perfect English (which they
don't), and even if they were all really good at
explaining things (which they aren't), this would
still produce bad documentation.  Why?  Because it
would only ever produce "What's this?" documents,
and never "How do I?" documents.

I find myself shooting down this idea every single
release cycle.

--
Shaun