Re: Online Help wrapping

[John Sheehan <john sheehan ireland sun com>]

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.

John

Gregory Leblanc wrote:
> 
> 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...
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list