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

[Shaun McCance <shaunm gnome org>]

On Fri, 2006-03-31 at 00:06 +0400, Nickolay V. Shmyrev wrote:
> В Чтв, 30/03/2006 в 11:02 -0600, Shaun McCance пишет:
> > 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
> > > >>>> 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.

[trimming]

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

And those are the most utterly and ridiculously useless
instructions.  We shouldn't have documentation like that.
Do we?  Yup, absolutely.  Should we enforce policy that
will put more crap like that in our documentation?  No.

For the first time in years, we actually have people who
are actively working on our documentation and trying to
fix this mess.  Let's not screw them.

--
Shaun