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

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
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
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.


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.


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]