It may seem comical, but it's a surprisingly common situation. I've encountered many companies that don't provide any user manuals with their products. If they do, their manuals are often horribly incoherent, or else years out of date. It shouldn't happen, but it happens all time.

Now, this problem is less common when buying off-the-shelf software or consumer electronics. That's because these products typically come from large corporations that pay attention to such details. Among smaller engineering firms though, this is a frequent occurrence. In fact, I'd estimate that about half of small engineering companies that I've encountered are guilty of this offense.

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 customers who suffer when manuals are inadequate or non-existent. What about 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 up to speed. Without it, they will be forced to rely more heavily on other engineers to educate them, thus wasting time of everyone concerned. Weeks, if not months, of valuable manpower can be squandered in this fashion.

Over 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 hope of preventing others from falling down 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 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 customers who suffer when manuals are inadequate or non-existent. What about 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 up to speed. Without it, they will be forced to rely more heavily on other engineers to educate them, thus wasting 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 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 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 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 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 prime reasons behind keeping thorough documentation—to make sure that company won’t be crippled by any person’s absence.

Unfortunately, many employees take opposite tack. They purposely scrimp on 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 short term, but ultimately, he’s a long-term liability.

3. Forgetting one’s audience