Re: Nine Months in Six Months

["BJörn Lindqvist" <bjourne gmail com>]

> > 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;

I disagree slightly. Bad docs means lowered usability. For example,
try this: open gnome-terminal, Edit->Current profile->compatibility
tab. Now I consider myself fairly computer-savvy but I can't figure
out what those settings do. Pressing the help button and reading the
documentation is unhelpful. So the settings on that tab pane are
completely wasted for me and, I suspect, for 99.9% of all
gnome-terminal users since they are incomprehensible.

But IF the docs had been written at the same time as the tab pane was
programmed, I believe that the problems with that pane would have
became apparent. Many features are easy to implement but hard to
document.

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

Many projects have a formal or informal guideline that unit tests need
to be included for new code to be accepted. That doesn't seem to have
slowed them down. But I agree that it is the documenters that must
write the documentation. But now they have six months to do it rather
than just the four weeks prior to a release when code freeze is in
effect.

--
mvh Björn