Re: Proposed: gDesklets

[Shaun McCance <shaunm gnome org>]

On Mon, 2004-01-05 at 02:54, Martin Grimme wrote:
> Am Mo, den 05.01.2004 schrieb Shaun McCance um 05:25:
> > gDesklets has no user documentation, though it does have a man page. 
> > This is a bit of a special case, as one would really want documentation
> > for each particular desklet one is running.  (However, there isn't any
> 
> Users tend to collect/install lots of desklets. Is it a good idea to
> have a manual for each of them clutter your scrollkeeper database?
> Maybe have a section GNOME/Desklets just like GNOME/Applets with several
> subdivisions. But who would maintain the documentation?
> Currently we count about 100 desklets at gdesklets.gnomedesktop.org.

I wouldn't say it's "cluttering" the ScrollKeeper database.  The idea of
having such a system is that we can categorize the documentation.  The
problem is that ScrollKeeper categories are a fixed vocabulary.  This
makes categorization really hard for programs that are a platform for
other programs.

This happens a lot.  For instance, the GIMP has a plugin system.  It
would be nice if plugins could offer documentation.  But how does one
categorize the documentation for GIMP plugins?  The same is true for
Gnumeric, which has an awesome manual.  But there's no intelligent way
to install documentation for Gnumeric plugins.

This is an issue that really must be addressed.  Fortunately, there's
discussion going on on freedesktop about a new shared documentation
system that can be used by GNOME, KDE, and other desktops.  So this is
an issue that can be brought up and dealt with.

As for who should maintain the documentation, people do manage to get
documentation written for panel applets.  Documentation can be a very
time-consuming task.  Most desklets, however, are pretty simple, and
their documentation doesn't need to be very big.  We're not talking
about writing 100 Gnumeric manuals here.

> > documentation for the default desklets.)  If this were included, we
> > would probably want to document its functionality in the User Guide. 
> 
> A user's manual for the core application, however, will be a must.
> gDesklets will get a user frontend in the future (right now, there's
> just the daemon) where a manual should be included. Help/directions
> from the GDP team would be highly appreciated.

Absolutely.  Regardless of whether or not gDesklets is included in the
GNOME Desktop, the GDP is willing to help.  We want to encourage better
documentation across the entire desktop, which isn't limited to just
those things that are officially in the GNOME D&DP.

> What we're currently working on is a developer's manual in DocBook
> format for desklet makers. Since this will be a manual, it should
> reside in the scrollkeeper database as well, shouldn't it?

My stance is that all documentation should be registered with the help
system.  If the amount of documentation there gets overwhelming (which
is a problem I'd love to have to face!), then we can start thinking
about narrowing what documentation is actually presented to the user. 
Most users don't need to see developer documentation, but this is an
issue that should be dealt with by Yelp.  All documentation should be
available through the help system.

--
Shaun