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

[Alan Horkan <horkana maths tcd ie>]

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/