Re: Nine Months in Six Months

[Shaun McCance <shaunm gnome org>]

On Thu, 2006-09-14 at 11:22 +0200, BJ�Lindqvist wrote:
> > > 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.

I wrote about a similar scenario about a year ago, except
I wrote about the Evolution account editor dialog.  See
the section "The Case for Help" here:

http://www.gnome.org/~shaunm/quack/mallard.xml

In this situation, the documentation does actually exist.
It's just not very good documentation.  If we required
people to submit documentation with all patches, I fear
we'd end up with more documentation like that.

Technically complete, but practically useless.

--
Shaun