The Top Five Mistakes that Companies Make
with Regard to Technical Documentation
BY V. BERBA VELASCO
EDITOR'S NOTE: This stuff's useful if you
provide technical writing services. Bookmark it! It may just help sell your
prospective clients on these ideas.
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.
1. 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.
2. Not 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
wayside.
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 liability.
3. 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.
4. 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.
5. 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 glance.
(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 I digress.)
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.
I 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? Maybe. Still, I hope that
some techies out there will read this message, and that they’ll take it to
heart.
V. Berba Velasco has a doctorate in
Electrical Engineering and has been plying his trade for nearly a
decade. Dr. Velasco currently works as a senior electrical and software
engineer for
Cellular Technology Limited, a biotech company in Cleveland, Ohio.
In his spare time, he raises dodo birds, builds human brains and plays
with his collection of magnetic monopoles.
 |
