RE: Online Help wrapping

["Phillip Shelton" <shelton usq edu au>]

A question from a lurker.  What should the help under the help button be?
Should it be a `Help file', what ever that comes to mean, or should it be
the same as the printed manual?

> -----Original Message-----
> From: gnome-doc-list-admin gnome org
> [mailto:gnome-doc-list-admin gnome org]On Behalf Of John Sheehan
> Sent: Wednesday, May 02, 2001 8:12 AM
> To: Gregory Leblanc
> Cc: gnome-doc-list gnome org
> Subject: Re: Online Help wrapping
>
>
> 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
>
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list
>