Re: Online Help wrapping

[Gregory Leblanc <gleblanc cu-portland edu>]

On 01 May 2001 14:38:11 +0100, John Sheehan wrote:
> Can we revisit a discussion regarding some of the supporting sections
> in online help.  This was touched on many months ago, but the 
> discussion never concluded.  

Sure, I like revisiting discussions.  Just don't mention mice.  :)

> The perception of the Gnome core as a consistent unified product is
> undone when a user clicks on an app's Help button.  Though the user
> typically wants to read just the help, they are also presented with:

I've taken a look at this list, and while there are a few that should
go, most of the others I feel are important to keep intact, or I don't
feel that they take away from our help system in any large way.

>      a copyright statement

Every document should have one of these on the first page.  Ever looked
at the printed manuals that you get?  They've got a printed manual.
I'll admit that our presentation of these could be better, I'd like to
see this header section take up less space, and be less prominent, but I
think it belongs.

>      a linked GDL license

Well, we certainly can't remove this, as in order to license our docs
under the GNU Free Documentation License, we need to link to this
license.  Actually, looking at the GNOME Calculator manual, I see only 1
line under the title, which reads "Copyright (c) 2000 by Gregory
Leblanc".  Copyright is a clickable link to the section which states the
license that the manual is distributed under.  I think is is very
similar to what KDE has, so I'm not sure which manual(s) you'r referring
to that have something different.

>      a bugs and limitations section

There are a few places where this is mistakenly left in (in the GNOME
Calculator manual, for example), but I don't see having it for programs
which -do- have known bugs and limitations as detracting from the look
of the system.  

>      a list of developers

Well, this is at the end of the manual, in a section explicitly labeled
"Authors".  Don't read this one if you're looking for help.  :-)

>      a support route for functional bugs

What are you referring to here?  The information in the Authors section
about how to submit bugs?

>      a list of authors

OK, this one -REALLY- belongs in the manual, as our authors deserve to
get credit for all of the hard work that they've put into these manuals.

>      a support route for documentation bugs

I take it this is referring to the information about comments and
suggestions for the manual in the Authors section?

>      a GPL license section

Again, I don't know why this is a bad thing, although I could see a
possible argument that it's not necessary in the documentation.  If it
got removed from the manual, it would -need- to be added as some feature
of the "About" dialogue box.

> Gnome Help will be perceived as a set of stand-alone mini-manuals 
> instead of as a unified help scheme.

Unfortunately, this is exactly what we have right now.  There isn't any
global indexing or searching, or any of the other features that you
expect from a system.  The "System" is that all of the manuals use
DocBook based on the recomendations from the GDP Handbook, and they all
get rendered using the same stylesheets.  This is going to change, but
there's a lot of infrastructure to build before it's a reality.

> By comparison KDE Help typically just notes the author under the title.

We don't list all of the above under the title...  

> It seems that several sections, such as the developer info and license,
> might better belong elsewhere, such as in the About button or in the
> source code directory (where indeed they already exist)

I don't think we should remove any of these from being accessable via
the GUI.  There's no reason that somebody should have to go digging
around in the filesystem in order to find out what rights they have
regarding this program, they should be able to just click and see the
license there.  I think that having the developers and authors listed in
the manual, or somewhere in the GUI, gives GNOME a much more personal
feel.  GNOME is Free Software, and GNOME is people.  If we remove the
authors and developers from the limelight, not only will we lose some of
their work, but we'll lose some of what GNOME stands for.

> Other sections might better be rolled up and accessible from the
> Help but not within the main body of the Help itself.

I think the TOC makes getting to, or not getting to these other sections
fairly straightforward.  I'll need to see some more discussion and
rationale before I'm convinced.
    Greg

-- 
Troll, troll, troll your post
Gently down the feed
Merrily, merrily troll along
A life is what you need...