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

[Andrew Sobala <aes gnome org>]

Sergej Kotliar wrote:
> > 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.
>   
One issue with that is that the bug would also be marked FIXED. Docs 
people would have to check for UICHANGE in open *plus* resolved bugs in 
the timeframe since the last release, which can get messy given that 
people branch at different times.

--
Andrew