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

[Sergej Kotliar <sigge hystrix se>]

> 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

An even easier solution would be to add the keyword UICHANGE to 
bugzilla, and let maintainers mark bugs with it whenever they
commit anything that changes the UI. In many cases, I think the
info in the bugreport would be enough. Of course - if it doesn't
have a bug report, one would have to be filed as Shaun suggested.

Sergej