Re: Nine Months in Six Months

> 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

  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

mvh Björn

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]