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

[Vincent Untz <vuntz gnome org>]

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.

Vincent

-- 
Les gens heureux ne sont pas press�