Re: reduce redundancy?

[Eric Baudais <drake x8b4e541f dhcp okstate edu>]

On Sat, Aug 19, 2000 at 10:52:03PM -0700, Kenny Graunke wrote:
> On Sat, Aug 19, 2000 at 10:44:12PM -0500 or thereabouts, Dan Mueth wrote:
> > On Sat, 19 Aug 2000, Kevin Breit wrote:
> > > Hey guys,
> > > 	I was curious if we'd be willing to save ourselves time!  Oh yeah we
> > > all do.  So now how to do that.  I figure we could put a template for some
> > > commonly used sections or what not.  For example, 90% of Gnome apps have a
> > > File/New
> > > File/Open
> > > File/Save
> > > File/Save As
> > > File/Quit
> > > Why don't we create a publically available text file, not even SGML, that we can
> > > use for other docs.  The other advantage to this, is that we'll know that all
> > > the docs have the same definition for Open or what not.  I just figure that
> > > it may take me 10 or 20 minutes to do a File menu, when it can, and should be
> > > spent doing other stuff.  I figure a simple template with all this stuff in
> > > it can save us all...just a little bit of time and redundancy

The manuals the GDP writes should have little to no redundancy in them.  This 
means you should not have an explanation of the menu item File/New in every 
manual which can make a new file.  Yet, someone might not know how to open a 
file in a particular application.  The problem is two-fold.  We need to 
provide to the newbie who got GNU/Linux and GNOME pre-installed and 
doesn't know much about computers.  We also need to provide documentation 
to the "power user's" need who wants concise and easy to navigate documentation 
which lets them find the answer to their specific, advanced problem.

Providing documentation which explains every last detail in a manual clutters 
up the documentation and makes the document hard to navigate.  This type of 
manual is not suited to experienced users of GNOME.  Advanced GNOME users 
will get bored because they a lot of the reading doesn't pretain to their 
problem and is very basic, while the problem can be complex.  They start 
skimming and will probably miss the important piece of information they 
need.  So when you include documentation about very basic features of the 
application, experienced users will get frustrated with the manual and 
eventually won't consult it anymore.

> > Do we all agree that we need to document all of the menus, even the
> > somewhat obvious ones like the ones Kevin lists above?  I get the idea
> > most people agree on this, but I just want to be sure.  (Speak now or
> > forever...)

Yes, we should document all the menus and what each should do.  This provides 
the necessary documentation for the user new to computers.  The documentation 
should NOT be put into the manual about each specific application though.  This 
will clutter the manual with documentation aimed at only a small group of people, 
newbies.  Cluttering a manual with basic explanations about GNOME menu items 
makes reading the manual for everyone, but a newbie, a tedious exercise.

I believe a better solution is to have a document for each menu item which 
is in most GNOME applications describing the menu item.  For example when the 
help button on a dialog is pressed, the help documentation about that dialog will 
be displayed.  For menu items which don't have dialogs, context sensitive help 
will start the help browser and display the explanation about the menu item.  
These documents will be global to all of GNOME because the components are the 
same for each application.

> All non-app specific GUI elements should go into a new global doc. This new doc
> would cover things like basic menus & menu items (File->Open, Edit->Copy, Cut,
> Paste, and so on). It would be geared for people new to the computer, as most
> computer users would most likely already know these basic elements.

I also think that all these explanations about the common menu items should be 
integrated into a larger doc for newbies.  This doc will have all the 
explanations about the common menu items in GNOME and also some more basic 
information about the GNOME desktop pertinent to a newbie.

I believe this solution has the advantages of providing only the information 
pertinent to a specific application in the manual.  It does not clutter and 
congest the manual with very basic information.  It provides the basic 
explanations about the common menu items in an easy to access manner.

Eric Baudais
<baudais@okstate.edu>