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: Documenting HW vs SW From:Richard Lippincott <rlippinc -at- BEV -dot- ETN -dot- COM> Date:Fri, 11 Nov 1994 14:35:04 EST
Dan Lupo asked what are the differences between documentation for hardware
and documentation for software.
I expect to get flamed for this, but:
Writing for hardware is more difficult.
I did hardware tech writing for a long time, I've recently started to do
software tech writing. The differences that I've observed:
*Software is often more accessible than hardware. I can get a copy of software
to run on my desktop, or I can walk to another part of the building and
see a version on a software engineer's desktop. Hardware might be all out
in the field, or in a hazardous location. The software engineer can show
me at his terminal how the software works. It is impossible for me to
view the workings inside the combustion chamber of a jet engine. It may
require the assistance of several technicians in order to disassemble a
complex hardware component.
*Software is simpler than hardware. For the most part, all the software that
we document runs on desktop PCs, LAN servers, and such. Even so, even
mainframes don't compare in size or complexity to a B-747 airliner, or a
nuclear powered submarine. Here are some relative page counts:
For the Air Force C-5 Galaxy transport aircraft:
Structural repair manual: About 3,000 pages
Corrosion Control Manual: 1,000 pages
Non-destructive inspection manual: 3,600 pages
Electrical systems manual: 2,000 pages
Flight Manual: 2,000 pages
(The complete set of aircraft manuals for the C-5 takes up about 20 feet of
shelf space.)
*Software is liner, hardware is not. Software is a program, it is a series of
steps executed in order. You can flow-chart it, you can theoretically get
a piece of paper that lists all the steps a computer takes, and the order in
which they occur. It's one-dimensional (at best, two-dimensional). Hardware
is three dimensional. For example, you can't understand the operations of
a jet engine without realizing it's three-dimensional, with rotation, -and-
those dimensions change as the engine gets hotter!
*Software is easier to create than hardware. From my observations, companies
that produce a hardware/software product combo have more engineers working
on the hardware than on the software. (That's only what I've observed, I'm
interested if othere observations match this.)
*Software is less painful. If a software writer and a hardware writer both
drop their company's product on their feet, the hardware writer's foot will
hurt more.
One last point, and I want to stress this this one very very much:
Hardware writers and software writers are EQUAL in skill, brains, and talent.
I'm certain that any hardware tech writer can transition to software. I have
no doubt that any software tech writer could have handled the hardware jobs
I've done over the past ten years.
That's my opinion. Reactions?
Rick Lippincott
Eaton Semiconductor
rlippinc -at- bev -dot- etn -dot- com
