The Top Five Mistakes That Companies Make with Regard to Technical Documentation

I've seen it time and again. One of the mostThis problem often occurs when developing user
common weaknesses that I've seen in engineeringdocumentation. Programmers and engineers
companies-indeed, an almost universal fault-is thefrequently forget that their manuals are going to
lack of proper technical documentation. Somebe read by people who are unfamiliar with their
would laugh this off as a minor detail; however,products, or who don't have the same technical
the repercussions are often severe. A company'sskills. I remember one company in particular-a
entire future can be made or lost based on themachine controller company on the west coast.
amount of attention they pay to this issue.Their "user manual" was a horrible hodge-podge of
Over the years, I've identified five problems thatacronyms, undefined terms and seemingly
I've found to be particularly common when itrandom thoughts, with about a dozen procedures
comes to writing technical documentation. I'd likelisted in no particular order. Their user
to share these thoughts with you, in the hope ofdocumentation lacked such basic details as how to
preventing others from falling down the samestart the controller up, or how to stop it in the
paths.case of an emergency-critical details that any
1. Not having any user manualsneophyte user should expect to find in a manual.
Don't laugh. This may seem like a fairly basicA related problem is the failure to use proper
mistake-absurd, even-but it is surprisinglylanguage. Consider the case in which many of the
common. I've encountered many companies thatreaders are not native English speakers-say, when
don't provide user manuals for their products, ormarketing a product in Europe or Asia, or when
whose manuals are skeletally thin or years out ofwriting assembly procedures for foreign-born
date. In fact, I'd estimate that about half of thefactory workers. In such cases, it may be
small engineering companies that I've encounterednecessary to keep the language fairly simple. If
fall into this category. (Of course, one seldomthis is not possible-say, when discussing complex
encounters this problem when buying off-the-shelfdetails that demand a great deal of precision-one
software or consumer electronics. Amongstcan often compensate by adding some
engineers though, it's a depressingly familiar story.)aptly-chosen charts, diagrams or photographs.
I remember how one engineer told me why hisEither approach can be helpful in making complex
company didn't provide any user manuals withtext a bit easier to absorb.
their products. In hushed tones, he said, "It's4. Not being suitably graphic
because we don't make any money by writingIt's undeniably cliché, but true nonetheless-a
manuals. It's not a money-making venture, so ourpicture does paint a thousand words. Similarly, a
management doesn't want to waste time on this."manual that makes judicious use of images and
An annoyed expression crept into his face, thendiagrams will be much easier to understand than
he leaned closer and said, "We have lost so manyone that is composed entirely of text descriptions.
customers because we don't have decentSome consider this to be childish and unnecessary.
documentation. Talk about being penny-wise,I don't, and my experience has shown that the
pound-foolish!"majority of users appreciate having these visual
It's not just the customers who suffer whenguides. Remember; no matter how sophisticated
manuals are inadequate or non-existent. Whatyour readers are, they're still human. Even an
about the employees themselves? What happensintelligent, otherwise careful reader can accidentally
when a new engineer comes on board, and hasmiss some important detail, especially when
to learn quickly? Or what happens when existingpressed for time.
engineers need to familiarize themselves more5. Not striving for excellence
with unfamiliar aspects of their product lines? TheIt's interesting to see how programmers and
user documentation, if properly written, canengineers can strive for excellence in many
provide a gentle and efficient way of bringing theaspects of their work, yet take the exact
up to speed. Without it, they will be forced to relyopposite approach when it comes to
more heavily on other engineers to educatedocumentation. "Who cares about wording
them, thus wasting the time of everyoneanyway?" I've heard many engineers say. "We're
concerned. Weeks, if not months, of valuablenot writing poetry or screenplays here. What
manpower can be squandered in this fashion.matters is that the documentation must be
2. Not having proper internal documentationtechnically accurate."
It's not just the user documentation thatThis is an appallingly short-sighted view. Technical
companies fall short on. Internal documentation isaccuracy is indeed important, but so are
frequently a casualty as well, as companiespresentation and style. Few engineers would listen
scramble to release a product. In their haste toto a job applicant who shows up in a bathrobe
bring products to market, companies often letand slippers, or a litigation attorney who speaks
their internal design documents fall hopelessly bylike a valley girl-and yet somehow, these same
the wayside.engineers expect their fellow techies (or worse, a
It doesn't help that programmers and engineerscustomer!) to slog through pages of meandering,
are notorious for having lackluster communicationpoorly phrased text. Even matters as
skills, and that documentation is a task that theyfundamental as spelling, grammar and proofreading
seldom enjoy. I've encountered many softwareare often treated as mere annoyances-piddling
companies, for example, whose software designsdetails that are worth nothing more than a
were an intractable mess due to their lack ofcursory glance.
architectural documents, interface descriptions and(To my relief, I have not encountered any such
in-code comments. Sadly, I've seen similarattitudes at my place of employment. I hasten to
problems when it comes to mechanical designs,say this, lest anyone think that I'm complaining
electronic designs, manufacturingabout the people that I work with! No, I've found
procedures… you name it.that we all appreciate the value of excellence, for
I've spoken to engineers whose companies havewhich I am always thankful. But I digress.)
either gone under, or have been teetering on theRemember: When writing for one's fellow techies,
brink. Almost invariably, lack of adequateone should bear in mind that they must often
documentation has been a major factor in suchabsorb voluminous amounts of information in
situations.scant amounts of time. When writing for laymen,
I always tell my bosses and co-workers, "I wantone should make the text as gentle and easy to
to make sure that my work is darned welldigest as possible, lest they become lost in an
documented. If I leave the company, or if I die inocean of geekspeak. Either way, putting a little
a car accident, for I want to make sure that thisextra effort into matters of elegance and style
company can march on without me." That shouldcan make a world of difference.
be one of the prime reasons behind keepingI won't go into detail about what constitutes good
thorough documentation-to make sure that thewriting technique, as that would be beyond the
company won't be crippled by any person'sscope of this text. Suffice to say that a good
absence.programmer or engineer should make sure that
Unfortunately, many employees take the oppositehis writing is readable and well-organized, and that
tack. They purposely scrimp on theit flows smoothly from one topic to another.
documentation, thinking that this will ensure themI would be thrilled beyond belief if I never saw
some job security-and sometimes, this works.another slipshod manual, or if I never heard
However, a smart employer knows that ananother story about companies collapsing due to
engineer who documents well is worth far morenon-existent documentation. A hopeless fantasy?
than another engineer who keeps his cards closeMaybe. Still, I hope that some techies out there
to his vest. The latter may be essential in thewill read this message, and that they'll take it to
short term, but ultimately, he's a long-term liability.heart.
3. Forgetting one's audience