Re: TW: Paperless Documentation

Subject: Re: TW: Paperless Documentation
From: Rose Wilcox <RWILC -at- FAST -dot- DOT -dot- STATE -dot- AZ -dot- US>
Date: Thu, 15 Jun 1995 14:40:00 PDT

Scott: Your second post describes what I consider a *lovely* help design.

Yes, I think it will work! The first post I read as a series of popup
process topics with no connection to each other, so I didn't have enough
information to understand your design.

I still wonder about the "redundancy" however. I agree that too much
branching can be unusable -- this is more true of hard-copy than of on-line
documentation (because it is harder to flip through pages of a book than it
is to click on an icon or a text link). However, in the help file, you want
brevity. Perhaps this is a case of me not understanding what you mean by
background information or what type of information is redundant.

For instance a design may have popups for every button on every screen.
Each time you explain the "close" button, it will be remarkably the same.
However, you want your users to be able to get the information with only
one click, so you explain it each time it occurs. This may seem redundant
from the writer's standpoint, but not from the user's.

Or you may explain on every window topic what the program does, what a
"window" is, etc. This is redundant and should be placed in a separate
topic; however, it could be just one or two clicks away if the user needs
it.

Rosie A. (the 'A' is for
----------------------------------------------------------------------------
--
Hi Rose,

> >I'm designing a hypertext document, based on modules.

> Modules? Application modules? How is the app organized? Are the modules
> task-oriented?

A module is no more than a screen and a half of text and
diagram. Some of the modules are task oriented, and some
are reference oriented. Each module contains certain
elements (title, summary, links, etc.).

BTW - The help screens pop up next to the user interface;
they do not cover it.



> >Each module is one help screen, but they also have a specific order.
> >The customer can click on a button in one of the initial help
> >screens to print out a manual, built from the help screens.

> Your developers is writing a .dll for this? Will this just print out the
> help screens in order or will it provide page numbers and TOC? If it is
> just printing out the help screens, it is *not* a manual!

It will not include page numbers, but the modules are
numbered by section (Section 2.1.4). This is what the
TOC includes.


> Are you allowing the user to browse through the sequence of modules within
> the help and read it like a book?


Yes.



> 2) Why do the modules have to stand alone? Can't you jump to "background
> info" modules from specific modules? That's what hypertext is for!

The short answer is yes, the user will be able to do this.
I view the hypertext as a means to navigate through the on-line
book. There are background modules, but that's not what will
pop up from an initial help call. Unless they are specifically
reading for background, I'd like there to be a single module
that answers their question, whether it be what a particular
button does or how a particular procedure works.


> 3) This redundancy alone is enough to make the "manual" printed from the
> help screens unusable, even if the potential lack of task-orientation
> doesn't...

Interesting. Edmond Weiss, in _How to Write Usable User
Documentation_, encourages redundancy, saying that the fewer
times a reader must switch between modules, the better. I
don't know many people who read a manual straight through,
so redundancy allows people to get their bearings without
having to read other modules. Does this make sense?



> In my experience, documentation organized around the program's
organization
> is more of a reference than a training document. If you cannot upgrade
the
> help system to include training or tutorial info, you should provide a
small
> hardcopy "getting started" guide -- unless the developer is willing to go
> out and train users at each and every installation.

The organization is both task oriented and program oriented.
The user interface is a series of tabs, much like the "Options"
screen in MS-Word. When the user clicks on the "Help" button
on any tab, the user can get help on any button or feature.
Also on the help screen is a list of the procedures involving
the tab. If the user wants to know what a button does, they
click on that button and a description pops up, along with a
hypertext link to each procedure which uses the botton.

The other option we are including, which is not a part of the
on-line manual, is a tutorial which gets the program running.
(Typically, once running the user does not need to touch the
software.)




> Rose A. (the 'A' stands for authoring) Wilcox
> rwilc -at- fast -dot- dot -dot- state -dot- az -dot- us
> ncrowe -at- primenet -dot- com
> "The shorter and plainer the better."
> Beatrix Potter



Thanks for your answer. :)


Scott McD.

--
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Stand hard-disk lame hers up lie. | Scott McDaniel
| Garcia Consulting, Inc.
I'm a citizen of Legoland, | (703) 412-3662
Travelling incommunicado! - Fish | mcdaniel -at- pioneer -dot- uspto -dot- gov


Previous by Author: Re: TW: Paperless Documentation
Next by Author: Re: Contract Work or No Contract Work?
Previous by Thread: Re: TW: Paperless Documentation
Next by Thread: FrameMaker vs. Interleaf


What this post helpful? Share it with friends and colleagues:


Sponsored Ads