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: Planning a Help Project From:"R. Darren Carlton" <wk06248 -at- WORLDLINK -dot- COM> Date:Thu, 31 Mar 1994 12:48:18 -0500
Just yesterday (Wednesday 3/30), my project leader charged me with finding
out how other people develop/design on-line help. We're considering using a
sophisticated tracking system (developed in Lotus Notes) to keep up with all
of the help topics, hypertext links, links to tutorials, etc.
Is anybody out there doing anything remotely similar to the following
description? Does anyone know of a simpler way to keep track of on-line help
topics, hypertext links, and context IDs?
OUR WRITING ENVIRONMENT
We currently have 12 team members working on our first Windows product.
Because we export into many environments (paper, on-line text retrieval
systems, on-line help -- all in multiple formats), we write the text in one
tool and then use macros to convert into other formats.
We try to shield the writers from having to understand the details of all of
the macros and formats. We want our writers to be free to research and write;
not to get bogged down in understanding IPF tags.
Since there are 12 of us developing a hypertext, we will have to do a lot of
up-front planning. We don't want writers to serendipitously add hypertext
links; it would become a testing and maintenance nightmare. So we try to
strike a balance between being rigid enough in our planning to allow us to
move from one publishing environment to the next while not stifling
creativity (although sometimes, IMHO, we err on the side of stifling
OUR WRITING METHODOLOGY
Our methodology is a combination of Information Mapping and Weiss's methods.
We separate information into modules based on information type. For example,
a module might be a step-by-step procedure, or it might be an explanation of
a concept. Usually, (but not necessarily) a module is from 1/2 to 1 page long.
This modular writing, all developed in one tool, allows us to quickly build
documents in different media. (e.g., all of the introductory modules might go
in on-line help as well as a "Getting Started" paper guide).
OUR DEVELOPMENT STRATEGY
Since we will have hundreds of modules being arranged in different ways
according to the medium in which they're published, and since many of these
modules will have hypertext links between them, we must have a way of keeping
track of where the modules live, where thery're published, who wrote them,
how they're made context sensitive, etc.
We plan to create outlines of these modules in a relational database (Lotus
Notes). We will also keep all of the technical information about the modules
in the database: context strings, aliases, keywords, medium in which it is
published, if it is context-sensitive, from which field can it be accessed.
Since the database will allow us to arrange the data in different ways, we
can use it to help us decide which modules need hypertext links between them,
which browse sequence we want to create, etc.
Once the outlines and arranging of the modules is complete, we're going to
pipe the data from Lotus Notes through a macro in MS Word that will properly
format the modules to be Windows help topics. (e.g., all of the context
strings will become footnotes with the "$" marker).
To minimize training needs, we've bought RoboHelp for our writers to author
in. Most of the technical formatting should be done by the Word macro
(freeing writers to write), but writers will still need a tool to help
compile their own work, to debug their work, and to facilitate including
grahics with hot-spots.
One of the many disadvantages of this system is that any changes made to the
RoboHelp/Word file must also be documented in the Lotus Notes database (if
the database is to be of any use for maintenance and developing test plans).
So while the database gives us some essential information and gives us the
ability to manipulate that information, it significantly increases the amount
of work writers must do to document their writing decisions.
HOUSE OF CARDS?
At times, it seems that we're developing an unnecessarily complicated system
for writing modular documentation. However, given our environment, we
certainly need a way to keep track of this information.
> How do other people develop on-line help, especially people in large
> How do other people test their on-line help to make sure all of the
hypertext links work and that pressing F1 in a particular field brings
up the right help topic?