Advice and guidance needed?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Peggy Luckett is <<... working in an environment without the kind of
collaboration with colleagues that I have enjoyed in the past.>>

Welcome to techwr-l. That's one of the many reasons why we're here.

<<The company I now work for... cranked out paper-based manuals in MS Word
that were later converted to PDF and burned on CDs for the customers.  Many
of these manuals are huge and all are laden with very techy language  that
is mostly peculiar to this industry and/or this company.>>

One thing you should try to do (when time permits) is find out how much of
the techy language is just a new vocabulary that _you_ have to learn, and
how much is really the _good_ kind of jargon: standard terminology that
speaks clearly to the experts who must use those words.

<<These manuals are essentially a description of the system interface and
functionality with a lot of CD/DVD theory. The "how to" is there, but you
have to wade through lots and lots of text to find it.>>

Which suggests that one good initial task would be to separate out the tasks
from the theory. Theory may still be necessary, but it shouldn't get in the
way of the tasks--it should support the tasks.

<<I've edited and cleaned up language and made some small changes in format
and the general flow of some of the manuals.  There are so many issues and
so much work, I hardly know where to begin.>>

Given that there's so much work to do, and that you're feeling lost about
where to begin, I suggest you spend however much time you need to do proper
triage: measure twice, cut once, as the carpenters say. Figure out which
changes will have the greatest payback for your readers, and forget about
the other changes until you've finished the really important ones. For
example, anything that could harm the reader or cause the reader to fail at
a task must be documented first, followed by the very small subset of the
larger body of documentation that is essential to doing a task. Second, and
only once you've finished that first part, set about doing the things that
would make the reader's job easier: if something is clear and accurate, but
takes a long time to puzzle out because of its length or lack of
illustrations or other factors, you can probably put it in this second
category. (Of course, if time is crucial, then such tasks get moved to the
first category.) Last but not least, go through and tidy up things like
style, formatting, etc. (That's not to say that style and formatting are
unimportant, since they aren't; what I'm saying is that you'll probably
create a "good enough" style and format while you do parts 1 and 2 of the
triage, and can polish this later.)

<<One major concern is that for many customers, English is not their first
language and there are no plans to translate our 
manuals into other languages.  Our products are used in so many countries,
it would not be feasible.>>

That's not a unique dilemma. Search the techwr-l archives for "simplified
English" and "controlled vocabulary" to gain some good insights into the
problem and past solutions. Editing so that your writing is simple, clear,
and unequivocal will go a long way towards solving the problems; editing to
cut out unnecessary text that was put there solely because it might
possibly prove useful to someone, some day, will also help. But possibly the
most crucial tool you'll need to create is a glossary of the key technical
terms. You'll use this for two important purposes: First, it'll help _you_
to use terms consistently and learn the language of your audience. Second,
it will provide definitions for anyone who doesn't instantly understand the
words.

<<Now, that same company may have one engineer and  employ a dozen
less-skilled people under the direct supervision of that engineer.  For that
reason, we are now developing systems for the Windows environment which are
much more "user friendly".>>

I always snicker when I see "user friendly" and "Windows" in the same
phrase. <g> But sarcasm aside, this means that you're now writing for two
very different audiences, and you'll need to both characterize their
different needs well enough to guide your writing (_and_ the design efforts
of your developers) and keep those differences in mind when you're writing.
That's not a simple task, but it's a vital one, and you can do it with some
thought and patience.

Your suggestions of editing the manuals for clarity and flow, and providing
a more useful index, are a good start. Separating information into Reference
and User's manuals (task oriented, step-by-step instructions), but with no
CD/DVD theory sounds good, with one proviso: sometimes readers need a bit of
theory to explain the context in which they'll be working, so you have to
separate the crucial from the less-crucial theory. A "short-cut guide" will
be particularly useful for the non-engineer audience, but I bet you the
engineers will love it too.

<<Assemble photos and include some explanation/instruction about the various
boards and connections of these systems.>>

Photos are simpler to produce, but may be far less effective than
illustrations where the goal is to show abstract concepts such as "this is
how part A relates to part B", or "insert the tab from this direction, not
that direction". Much of the problem comes from the fact that photos contain
enormous amounts of extraneous information, and can make it hard to find the
really important information you're trying to convey. Of course, photos are
important when visual fidelity is crucial. But you'll have to figure out
which situation calls for which medium.
  
<<a separate, small visual reference would be very helpful.>>

Possibly, but these are very difficult to create in a usable manner: for
example, do the round objects come before or after the square objects in the
guide, or should we really be grouping the black objects separately from the
red objects, and which of these two groups comes first? To be truly useful,
a visual reference must be tied to something more concrete and familiar,
such as the task order (e.g., a visual assembly guide) or the different
modules (e.g., the hard drive gets one illustration, the PCI cards get
another). My gut feeling is that you should integrate the visual reference
within the other manuals so that each illustration begins the section it
describes; you'll see this in most camera and VCR manuals, for example. This
approach uses the visuals to provide context and support for the text that
follows, and it can be very effective if well done. Providing the visuals in
an entirely separate guide runs the risk of making the visuals unavailable
when the reader is consulting the text, and having to open two manuals
simultaneously and juggle them while performing the task.

<<As for online help, I have attended RoboHelp HTML training... but, I'm not
convinced that it is the system we should use. Right now, our applications
are developed in Visual Basic for use in a Windows NT environment.>>

Online help has numerous problems--enough to justify writing a book about
its many defects. But the most serious defect (in my opinion) is that it's
rarely integrated with the user's task. Jef Raskin ("The Humane Interface",
Addison-Wesley, 2000) points out quite clearly that anything that takes the
user away from their current task (e.g., assembling a widget) and forces
them to perform an entirely unrelated task (i.e., opening a help system and
figuring out how to find the relevant topic) is inefficient at best and
highly counterproductive at worst. This is the rationale between the current
trend towards creating "embedded help", which ties the help information
directly to the task. Using "wizards", "affordances" (e.g., well-written
label text and tooltips, other visual and interface clues), and even help
frames at the bottom of each dialog box (so the help is already present and
doesn't have to be invoked by the user) are all possible solutions. You
mentioned that your developers are open to working with you, and if that's
the case, I urge you to explore these possibilities and push the limits. My
prediction: Modern Help technology is artificial, unintegrated with the
tasks at hand, unhelpful, and relies on technology so constraining that it's
difficult to actually help our audience. That being the case, I predict that
in 10 years or so, WinHelp and HTML Help will be distant memories--and ones
that a little psychotherapy will help us forget. <g>

<<Whether the use of Visual Basic and the Windows NT environment will
continue into the future is a matter up for discussion and further clouds my
decision about what product to use for the development of online help.  Or
should it?>>

It could well affect your decisions. Why tie yourself to a technology now
that will cause you problems later? Figuring out a means of creating help
that will be easy to convert into future technologies is well worth trying.
But you'll have to talk to your developers to find out what those
technologies are so you can find out your own needs for creating help in
that environment.

<<I'm hoping to travel to a manufacturing plant later this month so that I
can spend some time with a customer and shadow him/her/the process for a day
or two.>>

Excellent. Try to make this a standard practice now, so you'll be able to
continue it in future.

<<My boss, who was the lone TW for this company before I arrived, is very
helpful, but I think that he (and everyone that works here) is too close to
the forest to see the trees.>>

That's often true. I can certainly tell you how much I've learned from the
insights of newcomers or people less familiar with what I'm doing than I am,
and I've often changed my approach as a result. But never forget that
existing systems have often evolved for good reasons, and you need to
understand those reasons before you advocate change; sometimes the
underlying reason is crucially important, even if it gave rise to an
imperfect solution.

On the whole, your approach sounds eminently reasonable. I'd suggest you
keep in touch with techwr-l as future problems arise, but with two further
bits of advice: First, turn off whatever feature of your e-mail software is
adding all the markup tags (e.g., <param>) to your messages; these make
reading your message more difficult. Second, write shorter, more focused
queries; long questions provide a strong disincentive to answering.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Cub Lea, specialist in low-cost outsourced development
and documentation. Overload and time-sensitive jobs at exceptional
rates. Unique free gifts for all visitors to http://www.cublea.com

---
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.