On Thu, 30 Mar 2006, Shaun McCance wrote: > On Fri, 2006-03-31 at 00:06 +0400, Nickolay V. Shmyrev wrote:
> > > 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 > [trimming] Thank you. Please do trim messages, it really helps keep things readable. > > 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 Not the best example (as Shaun explained) but at least for smaller changes it would be fair to say if a developer changed menu item Foo->Bar and moved Foo->Baz it would not be unreasonable to expect them to check the documentation and make that small change in the documentation too to keep parity. > > 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. Hopefully maintainers will take this discussion as a request and will try to help encourage people to document their changes as they go along, especially the smaller more managedable changes. For example: New games for Ailseriot Solitaire tend to be added to gnome games only when suitable documentation is supplied, which is relatively easy because the games are variations on a theme and existing documentation can be recycled so only a paragraph or two needs to be written. Small changes I made to the button layout in gnome-cd were followed by an update to the documentation (unfortunately I failed to change the screenshot). Putting together a decent patch can be time consuming enough so while I appreciate the push to document what I had done I would not like to go too far and have reasonable changes be blocked and left to bit rot just because everything wasn't perfect. Balance is important. Sincerely Alan Horkan Inkscape http://inkscape.org Abiword http://www.abisource.com Open Clip Art http://OpenClipArt.org Alan's Diary http://advogato.org/person/AlanHorkan/ _______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
