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.
Subject:Re: TW: Paperless Documentation From:Rose Wilcox <RWILC -at- FAST -dot- DOT -dot- STATE -dot- AZ -dot- US> Date:Thu, 15 Jun 1995 11:43:00 PDT
>Hi all,
Hi, Scott.
>This is the solution
>that we're considering, and I thought I'd see if it evoked any
>comments from people who may have tried it before:
>I'm designing a hypertext document, based on modules.
Modules? Application modules? How is the app organized? Are the modules
task-oriented?
>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!
Are you allowing the user to browse through the sequence of modules within
the help and read it like a book?
>This will lead to fairly heavy redundancy since each module must
>stand alone in its context, but I don't view this as a bad
>thing.
Yucky! Yucky! Bad! Bad! (Sorry I lost it for a moment there.)
1) Help topics should be brief and concise.
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!
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...
>Has anyone tried an approach like this before? How did it work?
I would suggest:
1) analyzing the user tasks and adding background topics describing how to
do those tasks. You could include hypertext jumps from the "contents" page
and the related module topics.
2) Reduce redundancy to the full extent that you can, by separating
background information from specific-module information.
I *think* these principles would apply to even a simple application. But of
course, I can't see and analyze the application for myself....
>The programmer will be programming the help screens using .RTF
>files that I help produce.
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.
If you can obtain a help authoring tool, do so. For under $500 you can add
a whole range of helpful features for the users, including browse sequences,
glossaries, etc.
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
