By V. Berba Velasco Jr., Ph.D.
As published on www.simplysearch4it.com,
and www.ebooksnbytes.com. Copying of contents, in whole or in part, is permitted provided that the
author by-line is kept intact and unchanged. Hyperlinks and/or URLs provided by
the author must remain active.
I’ve seen it time and again.
One of the most common weaknesses that I’ve seen in engineering companies—indeed, an almost universal fault—is the
lack of proper technical documentation. Some
would laugh this off as a minor detail; however, the repercussions are often
severe. A company’s entire future
can be made or lost based on the amount of attention they pay to this issue.
Over the years, I’ve identified five problems that I’ve found
to be particularly common when it comes to writing technical documentation. I’d
like to share these thoughts with you, in the hope of preventing others from
falling down the same paths.
Not having any user manuals
Don’t laugh. This
may seem like a fairly basic mistake—absurd, even—but it is surprisingly
common. I’ve encountered
many companies that don’t provide user manuals for their products, or whose
manuals are skeletally thin or years out of date. In
fact, I’d estimate that about half of the small engineering companies that I’ve
encountered fall into this category. (Of
course, one seldom encounters this problem when buying off-the-shelf software
or consumer electronics.
Amongst engineers though, it’s a depressingly familiar story.)
I remember how one engineer told
me why his company didn’t provide any user manuals with their products. In
hushed tones, he said, “It’s because we don’t make any money by writing
manuals. It’s not a money-making
venture, so our management doesn’t want to waste time on this.”
An annoyed expression crept into his face, then he leaned closer and said, “We have lost so many customers because we
don’t have decent documentation. Talk
about being penny-wise, pound-foolish!”
It’s not just the customers who
suffer when manuals are inadequate or non-existent.
What about the employees themselves? What happens when a new engineer
comes on board, and has to learn quickly? Or
what happens when existing engineers need to familiarize themselves more with
unfamiliar aspects of their product lines? The
user documentation, if properly written, can provide a gentle and efficient way
of bringing the up to speed. Without
it, they will be forced to rely more heavily on other engineers to educate
them, thus wasting the time of everyone concerned. Weeks,
if not months, of valuable manpower can be squandered in this fashion.
having proper internal documentation
It’s not just the user
documentation that companies fall short on. Internal
documentation is frequently a casualty as well, as companies scramble to
release a product.
In their haste to bring products to market, companies often let their internal design documents fall hopelessly by the
It doesn’t help that programmers
and engineers are notorious for having lackluster communication skills, and
that documentation is a task that they seldom enjoy. I’ve
encountered many software companies, for example, whose software designs were
an intractable mess due to their lack of architectural documents, interface
descriptions and in-code comments. Sadly,
I’ve seen similar problems when it comes to mechanical designs, electronic
designs, manufacturing procedures… you name it.
I’ve spoken to engineers whose
companies have either gone under, or have been teetering on the brink.
Almost invariably, lack of adequate documentation has been a major factor in such situations.
I always tell my bosses and
co-workers, “I want to make sure that my work is darned well documented.
If I leave the company, or if I die in a car accident, for I want to make sure that this company can march on without
me.” That should be one of the
prime reasons behind keeping thorough documentation—to make sure that the
company won’t be crippled by any person’s absence.
Unfortunately, many employees take
the opposite tack. They purposely
scrimp on the documentation, thinking that this will ensure them some job
security—and sometimes, this works. However,
a smart employer knows that an engineer who documents well is worth far more
than another engineer who keeps his cards close to his vest. The
latter may be essential in the short term, but ultimately, he’s a long-term
Forgetting one’s audience
This problem often occurs when
developing user documentation. Programmers
and engineers frequently forget that their manuals are going to be read by
people who are unfamiliar with their products, or who don’t have the same
technical skills. I remember one
company in particular—a machine controller company on the west coast. Their
“user manual” was a horrible hodge-podge of acronyms, undefined terms and
seemingly random thoughts, with about a dozen procedures listed in no
particular order. Their user
documentation lacked such basic details as how to start the controller up, or
how to stop it in the case of an emergency—critical details that any neophyte
user should expect to find in a manual.
A related problem is the failure
to use proper language. Consider
the case in which many of the readers are not native English speakers—say, when
marketing a product in Europe or Asia, or when writing assembly procedures for
foreign-born factory workers. In
such cases, it may be necessary to keep the language fairly simple. If
this is not possible—say, when discussing complex details that demand a great
deal of precision—one can often compensate by adding some aptly-chosen charts,
diagrams or photographs. Either
approach can be helpful in making complex text a bit easier to absorb.
Not being suitably graphic
It’s undeniably cliché, but true
nonetheless—a picture does paint a thousand words. Similarly,
a manual that makes judicious use of images and diagrams will be much easier to
understand than one that is composed entirely of text descriptions.
Some consider this to be childish
and unnecessary. I don’t, and my
experience has shown that the majority of users appreciate having these visual
guides. Remember; no matter how
sophisticated your readers are, they’re still human. Even
an intelligent, otherwise careful reader can accidentally miss some important
detail, especially when pressed for time.
Not striving for excellence
It’s interesting to see how
programmers and engineers can strive for excellence in many aspects of their
work, yet take the exact opposite approach when it comes to documentation. “Who
cares about wording anyway?” I’ve heard many engineers say. “We’re
not writing poetry or screenplays here. What
matters is that the documentation must be technically accurate.”
This is an appallingly
short-sighted view. Technical
accuracy is indeed important, but so are presentation and style. Few
engineers would listen to a job applicant who shows up in a bathrobe and
slippers, or a litigation attorney who speaks like a valley girl—and yet
somehow, these same engineers expect their fellow techies (or worse, a
customer!) to slog through pages of meandering, poorly phrased text. Even
matters as fundamental as spelling, grammar and proofreading are often treated
as mere annoyances—piddling details that are worth nothing more than a cursory
(To my relief, I have not
encountered any such attitudes at my place of employment. I
hasten to say this, lest anyone think that I’m complaining about the people
that I work with! No, I’ve found
that we all appreciate the value of excellence, for which I am always thankful. But
Remember: When writing for one’s
fellow techies, one should bear in mind that they must often absorb voluminous
amounts of information in scant amounts of time.
When writing for laymen, one should make the text as gentle and easy to digest as possible, lest they become lost in
an ocean of geekspeak. Either way,
putting a little extra effort into matters of elegance and style can make a
world of difference.
I won’t go into detail about what
constitutes good writing technique, as that would be beyond the scope of this
text. Suffice to say that a good
programmer or engineer should make sure that his writing is readable and
well-organized, and that it flows smoothly from one topic to another.
would be thrilled beyond belief if I never saw another slipshod manual, or if I
never heard another story about companies collapsing due to non-existent
documentation. A hopeless fantasy?
Still, I hope that some techies out there will read this message, and that they’ll take it to heart.
About the Author:
V. Berba Velasco has a doctorate in Electrical Engineering and
has been plying his trade for nearly a decade.
During that time, he has repeatedly discovered the importance of good technical writing, and the pitfalls that can
occur from ignoring its value.
Velasco currently works as a senior electrical and software engineer for
Cellular Technology Limited (http://www.immunospot.com,
a biotech company in Cleveland, Ohio. During
his spare time, he raises dodo birds and builds human brains.