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.
RE: How is documenting hardware different from documenting software?
Subject:RE: How is documenting hardware different from documenting software? From:"Lippincott, Richard" <RLippincott -at- as-e -dot- com> To:<techwr-l -at- lists -dot- techwr-l -dot- com> Date:Fri, 7 Nov 2008 14:00:27 -0500
Leonard C. Porrello asked about the differences between hardware and
software documentation.
I've done both, and to put my hardware experiences in perspective I've
documented things like very large military transport aircraft, jet
engine maintenance, infra-red imaging systems, core network switches,
telecom systems, and currently very large scale high energy X-ray
systems.
--Is the process much different?
Yes, because the manufacturing process is entirely different. There's a
good side and a bad side to this. The good side is that for every piece
there has to be an exact manufacturing drawing, so you've got detailed
data on every component and every assembly. This information is
accessible even when the SMS's are hard to find, so long as you have
access to the engineering data (which you should by all means have).
The result is that the process tends to be more formal, and that's good
for us because often it means the documentation is taken into
consideration up front. With many customers, the documentation is highly
important and the requirements are a lot more structured than in
software.
There is also more responsibility for the writer: the contract might
specify that product may not ship until the manuals are ready. I was
also once in the unusual position that as the tech writer, I had final
sign off regarding certain engineering changes. (The full reason is a
long story, the short version is because the customer viewed the
engineering as part of the documentation and not the other way around.)
--Is the lifecycle of one generally longer or shorter than the other?
>From my experience yes, but that depends on the product.
The newly-built airplanes I was documenting in the 1980s are still
flying today and have a lot of years left on them, just this past August
at a nearby airshow I was climbing around inside a couple of planes that
I remember when they were bits and pieces of aluminum on an assembly
line. This can be good for a writer's job security in a couple of way.
One is that frequently (especially in aerospace) the customer will want
to upgrade and retrofit existing systems, and all this has to be
upgraded. For example in the 1980s there was a major job upgrading the
electronics systems in the C-5 Galaxy transport fleet, it was a major
overhaul to tech manuals that had first been written in the 1960s. Now,
the C-5s are once again undergoing an electronics upgrade, and getting
new engines. Again, all the old documentation has to be re-written.
(Plus in between there were lots of little jobs to do...according to my
friends who still work on the projects.)
Aircraft engines are an example of where the documentation requirements
are almost the opposite of software: with aircraft engines, the older
the product, the more work to do on the manual. New engines work well,
and early in the life cycle when parts fail they're simply replaced. But
as time passes, customers look at the more frequently replaced parts and
request "Can't you just tell us how to fix it?" Engineers are then
required to develop repair procedures, and we have to put them into
repair documentation.
--Does one generally entail better review processes than the other?
In my opinion, hardware documentation reviews are better. I've been in
cases where it's been as formal as walking through all the procedures,
with customer witnesses, and specific write-ups of how the documentation
will change prior to customer sign-off. There may be contractual
requirements that the review take place, and that there be proof the
procedures were tested on actual hardware.
--Is one generally more fun than the other?
Night time on a San Antonio flight line, shadows and arc lights
illuminating a B-52 undergoing maintenance...
The adrenalin rush from when you're pounded by sound waves as four TF-39
engines run up during a power-up procedure test...
Walking into an airplane at an airshow, and in the cockpit you spot a
tech manual you wrote years before...
Hiding fake contraband in your briefcase on the boss' orders, because
you're testing the resolution of a baggage scanner...
Firing up an 80,000 lb, 6 MeV X-ray system just so you can get some good
images for your manual...
Watching the news during a major disaster relief operation, and
realizing the food and medicine is being unloaded off an airplane you
documented...
Oh, lordy...hardware can be so much more fun.
--Anything else?
There's a good news/bad news about hardware documentation that is often
overlooked.
The good news: Because of manufacturing lead times, designs have to be
frozen far enough in advance that it gives you time to incorporate
changes before the manual is released. There wasn't any of this "Yes,
it's the last day before the release but we just made some significant
changes prior to last night's software build, all your screens are now
wrong." The manufacturing side needs time to actually build the new
parts, that gives you time to write about them.
The bad news: Unlike software, you can't always have easy access to the
product or see exactly how it operates in its natural environment. The
software that I've documented, I've been able to run on my desktop or on
a simulator. I can't run a jet engine at my desk, it's against safety
regs and the guy in the next cubicle would be annoyed.
Rick Lippincott
Technical Writer
AS&E*
American Science & Engineering
829 Middlesex Turnpike
Billerica, MA 01821-3907
978-262-8807 (direct)
978-495-2335 (mobile)
978-262-8702 (fax)
This message is intended only for the addressee and may contain information
that is confidential or privileged. Unauthorized use is strictly prohibited
and may be unlawful. If you are not the intended recipient, or the person
responsible for delivering it to the intended recipient, you should not read,
copy , disclose or otherwise use this message, except for the purposes of
delivery to the addressee. If you have received this e-mail in error please
delete it and advise AS&E immediately.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
