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

["Nickolay V. Shmyrev" <nshmyrev yandex ru>]

В Чтв, 30/03/2006 в 11:02 -0600, Shaun McCance пишет:
> 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 à 16:20 +0300, Nickolay V. Shmyrev a écrit :
> > >>>       
> > >>>> 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
> 

Let me disagree with Vincent's point that maintainer isn't able to
update user docs. Usually they contains just a set of phrases like:

To print document choose Menu->Print

That's all, we write API docs, why can't programmer write two lines like
above? Moreover there is quite advanced documentation guide. The main
question here to my opinion is a bit different - how to make this
practice more mandatory.