Re: Outlines for Hardware Documents

Subject: Re: Outlines for Hardware Documents
From: Robert Plamondon <robert -at- PLAMONDON -dot- COM>
Date: Tue, 11 Feb 1997 06:42:27 PST

I generally use the same format:

Chapter 1: Technical Overview, which contains a block diagram.
Chapters 2 through n-1: Description of the main functional blocks in
the diagram, one chapter per block.
Chapter n: Specifications.

This causes the block diagram to double as a document roadmap. I put
page or section references on the block diagram itself.

Engineers generally like this approach, since it's orderly. No one
complains about putting the Technical Overview in front, of course, and
it's very traditional to put the specs in back.

As far as the ordering of the chapters that describe the functional units,
I start with the sexiest units and work down to the most boring ones.
If the units are incomprehensible without knowing about other units first,
I'll put the other units first in violation of my sexiness rule. "Sexiness"
usually relates to verbish units: they DO things, either controlling the
rest of the chip (or board) or doing violent transformations to the data.
A nounish unit doesn't do much and gets buried in the back. A ROM is
a nounish unit.

If the product is complicated enough to have both units and subunits, the
same rules apply, but you have to maintain hierarchy. Units get chapters,
subunits get sections. This does not always work smoothly, and it's
sometimes necessary to cheat on the hierarchy, but the goal is to
present identical and accurate hierarchies in both the block diagram
and the structure of the remaining document. You may have to name
either units or subunits, which are often unnamed by the engineers.

-- Robert
--
Robert Plamondon, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 740-6509 * Fax: (541) 453-4139
http://www.pioneer.net/~robertp

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html


Previous by Author: Re: I am Tech Writer
Next by Author: Re: Contracting Moral Dilemma
Previous by Thread: Position in RTP, North Carolina
Next by Thread: Query: Using Word's Hidden Text as a conditional text hack


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

Sponsored Ads


Sponsored Ads