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