TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> >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
