Hardware guide summary

[Lois Patterson <lois -at- dowco -dot- com>]

I got some excellent general responses to my question about guides to
writing manuals about hardware. I also got some very helpful specific
guidance when I corresponded with some writers.

Here are the general responses:

********
One resource that should be easy to obtain would be published 
documentation for similar existing products. For example, if you 
are documenting a laser printer, you should be able to sneak a 
look at the manuals for a variety of laser printers at your local 
computer superstore with the cooperation of the sales staff; you 
could also order the manuals from the manufacturer if you're not in 
a hurry. Examine the manuals to find out what parts work well, and 
what don't work at all (e.g., ask the kind of questions you'd ask as 
a user, and find out whether the manuals answer those questions 
acceptably well). And the best resource of all: your customers!

That being said, you'll probably want at least the following sections, 
in roughly the following order:
- unpacking instructions
- information on getting technical support
- setup instructions, along with clear identification of where you 
could get hurt and what you need for successful setup (e.g., 
needlenose pliers, trinitrotoluene, and an arc welder; 100 kV DC 
hookup vs. 220 V AC). And no, those aren't real examples. <g>
- initial customization of the thingum you've just set up (e.g., 
leveling the supporting legs, removing the cardboard insert in the 
disk drive, setting the voltage switch and filling the grease
reservoir).
- instructions on how to use the device as a whole, plus each 
feature (ideally integrated in such a manner that they reflect how 
people should or will use the device)
- troubleshooting information (as extensive as feasible)
- information on supplies (e.g, consumables, spare parts), required 
maintenance, etc.
- technical specifications

*****
I have been documenting hardware for some time now, primarily in the
telecommunications industry. While I haven't found any hard-and-fast
rules/guidelines in print, I have devised an approach that works for me.
Some of these steps may belong in separate docs, based on your
documentation structure.
1. Get a product theory/overview -- where does it fit in the big
picture? what's it all about? Good source docs = Theory of Operation,
Hardware Specification, Hardware Requirements -- what does it connect to
upstream and downstream? is it bi-directional/duplex? is it
active/passive?
2. Determine how "deep" will the user have to go into the piece of
hardware, i.e., dip switches to set, covers to remove or not, etc. -- is
it the basic stick it in the rack and let it run "black box" or does it
require some savvy to operate? Beware, Smells often over-simplify at
this level.
3. Get into a lab and document an installation and startup of this piece
of hardware, then find someone in test engineering to try to "break" it.
They'll find the bugs and tricks that the user will need to know.
Another good SME for this would be a field installer or on-site service
rep.
My outline for a hardware doc (less the boiler plate front and back
matter) is basically: 
I. Product Overview 
A. Introducing the component(s) 
B. Where it fits in the big picture 
C. Theory of operation -- high level, layman terms 
II. Product Installation 
A. Pre-install checklists (Tools, etc.) 
B. Unpacking/Inspecting 
C. Pre-install configuration (if any) 
D. Physical Installation (mounting in rack, connecting cables, power-up
etc.) 
E. Soft Installation (operating software/firmware configuration) 
III. Product Operation 
A. Functional areas (grouped by buttons, types of tasks, firmware menu
options, whatever is most logical) 
B. Maintenance tasks 
IV. Troubleshooting 
A. During installation 
B. After installation 
Everyone has their own way of doing it, but this way works for me. Just
my $.02. 
*****
Another writer suggested the MIL-STD-38784A technical writing
specification at
<http://wpaftb1.wpafb.af.mil/tmss/index.html>
I have found this an excellent guide.

*****
Thanks for all of your help.


Lois Patterson
lois -at- dowco -dot- com