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.
Ask your management if you can talk to the company's best field service
engineer. He or she probably has the best troubleshooting skills, and
you can then try to document the way he or she thinks.
I am a former software engineer, former ski patroller, and full time
do-it-yourselfer, so I can also observe that troubleshooting is a
mixture of observation, experience, knowledge, and exploration.
* observation is what you sense as you look at something. What messages?
What signs? What was the user doing?
* experience is empirical knowledge. What are the most common problems?
What most commonly happens at
* startup
* shutdown
* age of machine
and so forth
If you look at FAQs for software, you usually see entire sections
devoted to installation and upgrading,
because many problems occur at that time.
* knowledge is reading, training, and understanding of how the machine
works. If you know that your brain needs
oxygen to function properly, and you observe that a patient is not
responding intelligently to your questions,
then you might conclude that the patient isn't getting enough oxygen.
* exploration is testing of hypotheses you generate from observation,
experience, and knowledge. If you know that
your machine often fails to start up because a connection has come
loose, and you know the machine was moved
recently, then when it doesn't start you take off the cover to see if
the connection is loose.
Joe
Joe Malin
Technical Writer
(408)625-1623
jmalin -at- tuvox -dot- com
www.tuvox.com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.
-----Original Message-----
From: techwr-l-bounces+jmalin=tuvox -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+jmalin=tuvox -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
Of Glen Blair
Sent: Tuesday, March 07, 2006 11:22 AM
To: TECHWR-L
Subject: Developing a troubleshooting guide
Hello all,
I'm a relatively new tech writer at an engineering company that builds a
specialized type of machine. One of the newer machines has caused some
problems for our customers. A malfunctioning machine typically exhibits
one of five or six general symptoms, but the cause of the same symptom
can differ from machine to machine. Diagnosing the problem is often
complex and regularly requires our field service engineers and customer
support engineers (manning the phones) to refer customers directly to
engineers working in research and development.
I've been asked to develop a troubleshooting guide to help the field
service and customer support people better diagnose and solve the
problems they encounter with this particular type of machine.
Unfortunately, there's very little in the way of "official"
documentation for dealing with and fixing properly-diagnosed problems.
Much of the information I need is in the heads of individual technicians
and engineers, and in "unofficial" emails exchanged by those emails
(which I'm currently compiling).
In a nutshell, I need to develop a troubleshooting guide that will allow
its reader to work from a general problem to one of myriad possible
causes (which could be hardware- or software-based) and appropriate
solutions. I'm having some trouble figuring out they best way to
structure this without sacrificing its usefulness. Can any of you share
the approach you took in a similar situation? Or are there any good
articles or books out there you can recommend?
Thanks,
Glen
--
"The atmosphere of the average workplace is to productivity what flames
painted on the side of a car are to speed."
-Paul Graham
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
