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

[Shaun McCance <shaunm gnome org>]

On Thu, 2006-03-30 at 16:34 +0100, Andrew Sobala wrote:
> 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.

Right.  Maintainers won't want to leave those bugs laying
around open, because they get in their way.  I don't know
how everybody else works, but I generally use bugzilla as
my TODO list.  If my bug list were full of things that I'd
already done, it would make bugzilla less useful.

On top of that, it's hard enough for documentation folks
to use bugzilla for documentation things already.  Bugs
are spread out across so many products with varying names
of components for documentation.  (A few still don't even
have docs components, despite my constant pestering.)  We
often just want to say "What can I do?" rather than "What
needs to be fixed in this document?"  That's already not
easy, and if we had to look for keywords outside our docs
components as well, it would just make things harder.

--
Shaun