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 _______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
