Re: Including instructions which require GConf

[Shaun McCance <shaunm gnome org>]

On Tue, 2008-01-08 at 13:34 +0000, Phil Bull wrote:
> Hi guys,
> 
> On Mon, 2008-01-07 at 19:56 +0000, Don Scorgie wrote:
> > If you think the ability to change the number of items displayed is
> > important to users, I would file a bug against deskbar applet asking for
> > a configuration option.  Otherwise, maybe adding a small part like:
> > "You can change the maximum number of displayed items by changing the
> > gconf key
> > /apps/.../...
> > "
> > which is what other manuals do.  It's not the ideal solution, but it's
> > something.
> > 
> > Maybe something more to add to the style guide (Shaun).
> 
> Thanks for the advice. I've now sent an updated patch to the Deskbar
> maintainer which removes the section which refers to gconf.

Jumping in late, but I tend to think that documentation
shouldn't shirk away from shortcomings in applications.
So if this is really a feature users should have access
to, then of course its absence should be considered a
bug.  But the documentation is there to tell users how
to get things done, and that includes how to get past
known bugs and limitations in the application.

Now, of course, whether this particular feature should
be considered necessary and documentation-worthy is an
open question.  I'm inclined to say no.

(Don, as for Style Guide updates, I would like to come
up with a strategy that allows us to put advanced topics
in our documentation in a manner that is both consistent
and unobtrusive.  If I had such a strategy, I'd surely
put it into the Style Guide.  But I'm afraid I don't.)

--
Shaun