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.
I envy you. I love writing about hardware! IMO, it is easier to write
about hw than sw because you can see it.
Generally, the user wants answers to the following questions:
* Why do I need this thing; What does it do; How does it work; What
does it look like? (Product description)
* Do I have to prepare my site in any way for its arrival? (Planning
and Engineering (or Site Preparation) Guide)
* How do I install it; If I do something wrong, will I die?
* How do I maintain the system; What parts are likely to wear out;
how long will they work before they fail; how do I get new parts?
(Routine Maintenance Procedures)
* What does it mean when the red and yellow LEDs light up; How do I
turn off that awful alarm? (Alarm-Clearing Procedures)
You will probably also have to create a configuration guide. This will
take you into your comfortable sw zone, but sometimes users can
configure the hw by connecting a "dumb terminal" to it. In this
situation, the "sw" is inside the hw and you will need to create a
command reference guide for it.
When you go to your meeting, decide that you will ask questions that
relate to only one of the documents listed above. So, follow Chris
Christner and other's excellent advice, but not all at once. That is, if
you decide that you will ask only installation-procedures questions at
the first meeting, you don't need to ask about power, ventilation, and
flooring, or the equipment the customer has to have on hand, for
example, because you will deal with those when you have the
The hardest documents to write are the product description and the
alarm-clearing procedures, so save these for last. Alarm-clearing
procedures are hard to write for several reasons:
* Engineers believe it is impossible to provide you with alarm
information ("There are too many; they are generated from deep
down in the system; that alarm never happens;" blank stare)
* Alarms are in the realm of both sw and hw, and the electrical
engineer does not have a clue about what the mechanical engineer
does, and vice versa.
* The format of the document will probably be significantly
different from the others and so you will have to create a new
template or do some extreme modifications to the existing one.
The product description is hard to write because the only person who
knows everything about the product is the VP of Engineering or some
other equally intimidating person. As I implied above, rank-and-file
engineers know only about the thing they are working on, so asking one
of them to describe how the whole product works is like asking the
bricklayer to describe the whole building.
Someone said that you have to be mechanically inclined to write about
hardware. I disagree. I am not at all mechanically inclined (I blame my
engineer dad--whenever I asked if I could help with whatever he was
working on, he'd hand me a screwdriver and say, "Here, hold this."), but
I can write about mechanical things. Certainly there are times when,
despite my calm demeanor, my brain is screaming, "Ack! I don't
understand!). When I start to panic like this, I remind myself that
hardware is just like "the shin bone's connected to the thigh bone." If
you are really having trouble with some of the concepts, buy one of
those kids' electronic kits or download the instructions for an
electronic science-fair project.
Finally, does the two-hour SME limit mean one two-hour stint each week,
or can you spread the two hours over the whole week? Your progress will
be seriously impeded if it is the former. If you are stumped on Thursday
(and you will be), are you going to have to wait until next Wednesday to
get an answer? You need to have access to the SMEs during all working
hours. Their work is no more important than yours.
No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.308 / Virus Database: 266.9.1 - Release Date: 01/04/2005
WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo: http://www.webworks.com/techwr-l
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.