Re: Documenting Hardware....yikes

[Lyndsey Amott <amott -at- docsymmetry -dot- com>]

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?
     (Installation Guide)
   * 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 
planning-and-engineering-guide meeting.

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.

Lyndsey Amott
www.docsymmetry.com


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