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.
dan roberts is documenting <<...mainframe (ISPF) procedures that can include
a number of runtime options. The user specifies input data sets and runtime
options on the initial screen. Depending on the runtime options the user
selects, various other screens might appear, one per option.>>
Sounds like this is a job for either a good flowchart (showing the decision
points at each branch, and the resulting Configuration after choosing a
particular branch) or a table that accomplishes the same purpose. Here's how
this might work:
In the flowchart, let's say the first box is "component screen"; there would
then be a branch for "choose filters" and a second branch for "choose report
titles". After each branch, you'd present a summary of the new state of the
software after taking that branch as a "story of the film so far" aid to the
user. So in the first case, you'd have "components and filters selected",
with two more branches coming off this box: "choose report titles", and
"choose report parameters". If the person chose the first branch, they'd
arrive at a box labeled "components, filters, and report titles chosen",
with additional branches for the remaining choices. And so on. At the end of
the branching, you'd have a final box that says "see the section
Configuration X, on page Y", which is a pointer to an explanation of the
current state of the software and what to do about it. (I'll come to that in
a moment.)
A tabular approach might work similarly, but would be easier to implement:
In the first column, list all the screens the person could select. Across
the top of the table, list the various configurations that result
(Configurations X, Y, Z, etc., plus a page number where the resulting
Configuration is explained). You have several options for such tables: Put a
check mark under each option to show whether it has been selected for a
given Configuration, use a number instead to show the sequence in which it
was selected, or delete the whole first column and put the options chosen
(in the order they were chosen) under the appropriate Configuration heading.
Users then need only compare their choices with the list of possible
Configurations to know which configuration most closely matches the one
they've chosen.
Since much of the information would be duplicated (e.g., the "insert your
name here" field will be the same no matter which configuration path the
user selects), this situation is tailor made for online help: you write the
explanation of a field once, and users simply get the reference information
by hitting the system's help key with the cursor in that field (this calls
up the same text in each case). If you use the Configuration approach, the
final text that explains the Configuration could be done in much the same
way that baseball cards are produced: each contains the same fields, but
with different options filled in. So you could do the same thing, but
substituting "cost" for "earned run average" or "output options" for "runs
batted in"; in effect, the "baseball card" for each Configuration would have
the same category of information at each position on the page, but different
values or options filled in beside that category.
--Geoff Hart, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"The paperless office will arrive when the paperless toilet
arrives."--Matthew Stevens
