Advice and Guidance Needed

Subject: Advice and Guidance Needed
From: "Peggy Luckett" <peggyl -at- dcainc -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 31 May 2001 16:12:44 -0500

<color><param>0100,0100,0100</param>This is a very lengthy request for help. I am working in an
environment without the kind of collaboration with colleagues
that I have enjoyed in the past. I need someone to bounce ideas
off of, as well as some guidance. In February of this year, I
began working as a TW for a company that is the world-leader
in signal processing technology. Despite that lofty description,
they are a small company based in a small (pop. less than 8,000)
rural town in the US.

<bold>First, a little background:</bold> This is my second job as a ?full
time ?techy? technical writer.? For about five years, I worked
for a company that produced computer-based training for
fortune 500 companies. We used Authorware, Dreamweaver,
etc. , but I wrote trainings for all sorts of jobs, put them online,
headed QC, arranged photo shoots, lead projects, etc. I made
the transition from that company to a technical writer position
with a company that contracted with the Federal Government
developing systems for the Air Force. That is a completely
different world and another story.

<bold>The present:</bold> The company I now work for develops
applications and hardware for companies all over the world who
manufacture CDs and DVDs. At present, none of the
applications have online help systems. Until they hired me, they
had one technical writer. He wore many hats and 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.
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.

I have spent the past four months reviewing current manuals and
attending training with technical support personnel from
Malaysia, Taiwan, Germany, etc., 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. On the plus
side, the company is very receptive to any ideas or changes that
I might suggest and the developers are a good group, very
helpful. We will eventually begin to produce online help for the
applications, but because of the complexity of these
applications and the entire manufacturing process, the need for
a paper-based manual will continue.

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. But, simplifying the
language used in the manuals would be a great help. Akin to this
problem is that the CD/DVD manufacturing industry is changing.
In the past, a manufacturer might have a dozen or more
engineers. 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.? By ?user friendly? I don?t mean to imply that
just any computer literate person would be able to use these
systems. Never-the-less, they are going to be a significant
improvement. Of course, that doesn?t mean that our existing
systems will disappear. We will still have customers using the
existing systems and our company will continue to provide
support and updates for those systems. My most immediate
concern is for those existing systems and I am contemplating
the following:

<paraindent><param>out</param>When the products are updated, edit the manuals for
understandability and perhaps reorganize the content into a
more logical flow. Expand and develop a more extensive
and useful Index for each manual.</paraindent>

<paraindent><param>out</param>In addition to the Reference Manual, develop a ?User?s
Guide? for each product. These would be task oriented
guides, with step-by-step instructions, but a much
leaner/meaner guide with no CD/DVD theory.</paraindent>

<paraindent><param>out</param>Develop a one or two page ?Short-cut Guide.? Many of these
systems have short-cuts that are not listed anywhere.
Sometimes they are listed in the manual, but once again,
they are buried in the body of text. Nobody reads a manual
from cover to cover, so I doubt that most users know many

<paraindent><param>out</param>Assemble photos and include some explanation/instruction
about the various boards and connections of these systems.
These are in the existing manuals, but they are not easily
found. I?m thinking that a separate, small visual reference
would be very helpful. Something that is not buried in 300
pages of text. We fly support people all over the world only
to find simple connection problems or loose boards caused
by physically moving the system from one place to another.</paraindent>

I leaning towards following a similar path -- reference manual,
user's guide, short-cut guide, and an illustrative guide of the
boards and connections -- for the next wave of products that
will be developed in a more user-friendly Windows environment.
We intend to also have online help with those products.
Whether we will develop online help for the old products as
they are updated/bugs are fixed, etc., has not yet been

As for online help, I have attended RoboHelp HTML training,
have used it a bit in a previous job, and have spent quite a bit of
time learning more about it. But, I'm not convinced that it is the
system we <italic>should </italic>use. Right now, our applications are
developed in Visual Basic for use in a Windows NT environment.
These systems/applications are used in a manufacturing plant.
Often, they are stand-alone computers. Most do not have
Internet access. 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?

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. We have very
knowledgeable people here and many have spent time at
manufacturing plants, but there are big gaps of knowledge
about the entire manufacturing process and, of course, it
changes continually. Even so, I think that the more I know
about the entire process, the more able I will be to write a
user?s guide that will truly be useful.

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. From
what I?ve related to you, do you think I?m heading in the
right/wrong direction? Any thoughts, reference books,
guidance, or words of advice from you seasoned pros would be
most appreciated.




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

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See or 800-463-6627 for more about our solutions.

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 for more resources and info.

Previous by Author: New tech writer employment tips?
Next by Author: Re: Writers face prison in Russia
Previous by Thread: Re: Really Dumb Question: Commas
Next by Thread: Define Features and Benefits

What this post helpful? Share it with friends and colleagues:

Sponsored Ads