Re: Documenting Hardware....yikes

Subject: Re: Documenting Hardware....yikes
From: Lyndsey Amott <amott -at- docsymmetry -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sun, 03 Apr 2005 13:01:04 -0500

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

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


Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:

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

Previous by Author: Re: Portfolios (and another question)
Next by Author: Re: What is wrong with this sentence?
Previous by Thread: Re: Documenting Hardware....yikes
Next by Thread: Re: Documenting Hardware....yikes

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

Sponsored Ads