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.
Jim Shaeffer reports: <<How do you document step-by-step instructions for an
ever-changing GUI?>>
Work with the developers to accomplish two goals. First, ensure that the GUI
itself carries as much information as possible on the sequence of actions
(e.g., move from top to bottom of a dialog box, with no decisions required
re. "do I go to the right side next or work down to the end of the page
before returning to the righthand column?"). Second, ensure that each
interface widget that's added dynamically has its own hook to its own
context-sensitive help. This can be as crude as putting a little [?] icon
beside each field to provide help for that field alone, or as sophisticated
as embedding help in the components of the interface rather than requiring
users to access an external help file.
Combine these two approaches, and write help text that is as free of context
as possible and you're well on your way to a solution. If a given chunk of
text has different prerequisites at different times, try to cover each of
these possibilities somehow. See Mark Baker's comments on normalizing text
(last week?) and the ensuing discussion for valuable clues.
<<The strategy is that the independent presentation layer will allow our
software to run anywhere and everywhere (desktops, laptops, tablet PCs, hand
helds, PDAs, cell phones and devices that haven't been invented yet).>>
I'm not convinced you can design something efficient for a 17-inch monitor
that will work on a cell phone or vice versa. That suggests you may want to
re-examine your strategy here. The various media you've listed have such
different constraints that your solutions will inevitably be different; for
example, I don't think you can have a dynamically generated Web-help system
on a cell phone or PDA. You may need to develop some form of single-sourcing
that will let you provide the same instructions in very different media.
<<Our users need detailed, step-by-step instructions for every task they can
perform while using our software. They complain that we don't give them
enough step-by-step procedures, and they have amply demonstrated their need
for them over the years. Further, it is obvious that there is no such thing
as too much hand holding or too great a level of detail.>>
If that's true, then the solution is to turn the dynamic interface into some
kind of "wizard", even if you don't use true Microsoft Wizard technology.
For example, let's say that your procedure can take anywhere between 5 and
10 steps. You could certainly build these into a single window that's
functionally equivalent to a dialog box, with the window expanding or
contracting to fit the content, or you could present each step in its own
window, in a sequence determined by the dynamically generated interface.
Putting each step in its own window lets you design the window optimally to
support the user; for example, provide the basic information on the step at
the top of the window, the widgets that let you perform that step in the
middle, and the detailed help at the bottom. Each step is then indissociably
bound to its help text; experts can jump right into the widgets without
having to read the details, while neophytes can read the detailed help
before proceeding; and the smaller, more concise and efficient windows will
be easier to transfer to a PDA or other medium with limited display space.
<<Our user documentation is in the form of context sensitive Help files.
Traditionally, Help files are tied to executables. Our plan, is that the
executables will remain constant while the GUI (presentation tier) adapts
itself to any and every delivery device.>>
It's a myth that help files must be tied to executables. A truly primitive
example might be to create a separate help file for each field, with no
overt links to the rest of the help system. Then all your programmers need
to do is create a button for each widget in a dialog box that says "when
this button is clicked, launch [hardwired filename] in [display software]".
An integrated system such as WinHelp can be considerably more efficient, but
don't forget that this isn't your only solution.
<<The strategy of the independent presentation layer is part of our plan to
get our software to be installed and used by people who are even less
technical than our current user population.>>
"Flexibility" and "really, really nontechnical user" are gasoline and Zippo
lighter: they don't mix. If your audience really is primarily a group of
nontechnical people, providing lots of choices is only going to confuse
them. It took me many years of editing to learn that most of my authors (the
majority with PhDs) got confused when I presented more than a couple
alternatives; most just wanted my best guess at the correct solution. I
strongly suspect the same will be true of your nontechnical users. The truly
timid user will see the interface change and will feel completely out of
control: "Hey, it didn't do that last time! How do I get to work the old
way?"
That being the case, you may want to provide a very rigid (programmed and
guided) interface for the neophyte or timid user--something that guides them
through the sequence of steps with minimal thought required--supplemented by
an optional "power user" interface that is completely dynamic. The former
users will be able to follow a sequence of steps that you consider
effective; the experts will be able to customize those steps.
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
(try ghart -at- videotron -dot- ca if you get no response)
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"Wisdom is one of the few things that look bigger the further away it
is."--Terry Pratchett
NEED TO PUBLISH YOUR FRAMEMAKER CONTENT ONLINE?
?Mustang? (code name) is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to Web, intranets, and online Help.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! See a live demo that
will take your breath away: http://www.ehelp.com/techwr-l3
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
