Re: Online Help wrapping

[Dan Mueth <dan eazel com>]

On Tue, 1 May 2001, John Sheehan wrote:

> If I invoke the Panel Manual, I get a piece of 'pure' help for what is
> a major Gnome feature.  If I invoke help for the simplest of applets, I
> may get a TOC in which less than half of the entries relate to actual 
> help.  As a user, I find the former friendly, and the latter overwhelming.  
> 
> Definitely there must be a facility for credits, copyrights and licensing
> where it can be accessed when the user wants to access it.  But I don't
> believe it is user friendly to put it all in the main body of the help
> and expect users not to read it if they just want help.  A single link,
> perhaps directly beneath the title, could bring the user to a page which
> contains this information - it could be the equivalent of an About button.

We have some work to do here.  I think for GNOME 2.0 we need to review our
template and stylesheet carefully and consider ways to simplify what the
user sees.  We have quite a bit of boilerplate on each document, and much
of it can be removed or else moved to a less conspicuous place.  For a
while we had the attitude of throwing everything a user could ever want to
know into the manual in a toplevel section.  I think we should be more
picky about what information we throw at the user and more creative about
how we present it.

Our boiler plate sections are:
  * Known Bugs and Limitations
  * Authors
  * License

Known Bugs and Limitations:
As Greg suggests, we should remove this from most docs unless there is a
legitimate need for the section.  If there is nothing really serious to
put here, we should remove the whole section.  Most documents have this
section and then says something like "no known bugs", which I now realize
is lame. (yeah, I'm slow)

Authors:
Right now we use this to: (1) list the app author, (2) list the doc
author, (3) explain bug reporting.  We don't really need to do (1), as
this need is served by the About dialog.  We also don't need to do (2),
since the authors are listed in the copyright statement.  The bug
reporting is now described in a new document written by Sasha.  It may
make sense to keep a sentence linking to Sasha's doc, but I think the rest
of this section could go.

License:
This lists the doc license and the app license.  This section is
redundant, since the doc license is given by the "copyright" link and the
app license is (or at least should be) listed in the About dialog.

So, I think we could get rid of all three of these sections (except Known
Bugs and Limitations for just a couple docs) with no loss except the loss
of the link to the Reporting GNOME Bugs doc.  I'm not sure whether this
one link justifies a section of its own or not.

What do people think about these suggestions?  It would make docs look a
lot more like online help than they currently do.

We also need to review our stylesheet and consider various changes to
improve the appearance of the docs, although this is really a seperate
discussion.

Dan