Re: Keeping user docs up-to-date with applications

[Shaun McCance <shaunm gnome org>]

On Fri, 2006-03-24 at 21:15 +0100, Vincent Untz wrote:
> Le vendredi 24 mars 2006 �6:20 +0300, Nickolay V. Shmyrev a �it :
> > While looking on discussion of removed screensaver button and work
> > work on GNOME docs translation, one interesting idea came to my mind.
> > 
> > Usually UI changes are accepted without change in user documentation
> > thus making docs obsolete (for example, user docs still mention
> > screensaver button and even more, they tell user about "Add to panel"
> > popup menu with submenus). From other side, maintainers often reject
> > patches with bad formatting or other code guidelines violation. Isn't it
> > better to require that every UI-related patch should have doc patch as
> > well. Usually new API should be documented, why do we ignore user docs?
> > They aren't less important than coding style, probably they even more
> > important.
> 
> The thing is that the docs are usually not maintained by the modules
> maintainers. It's easy to reject (well, mark as "needs-work") patches
> because of formatting or non-documentation of new API since those are
> stuff that is the job of the maintainer. Not to mention that I wouldn't
> qualify as someone who can write some part of the doc :-)
> 
> Also, this is why the UI freeze does exist. Maybe it's too late for
> documentation people, though. IMHO, a good first step would be to ask
> maintainers to list all the big changes that has been done before UI
> freeze.

Agree completely.  Another option, however, is that whenever
maintainers do something, they file a bug against the docs
component of their product in bugzilla.  Generally speaking,
this means that every time a developer spends hours and hours
implementing a new feature, he needs to spend an additional
five minutes writing a very basic outline of what the feature
does in bugzilla.  A particularly nice maintainer might also
list anticipated common gotchas or other quirks.

Heck, if the feature (or substantial UI change or whatever)
was implemented in response to a bug, the maintainer needn't
even file a new docs bug.  He can just change the component
of the existing bug, rather than closing it.

This would give the documentation team a much better chance
of documenting as we go, rather than in one lump sum at the
end of the release cycle.

--
Shaun