I’ve seen it time and again. One of
most common weaknesses that I’ve seen in engineering companies—indeed, an almost universal fault—is lack of proper technical documentation. Some would laugh this off as a minor detail; however, repercussions are often severe. A company’s entire future can be made or lost based on amount of attention they pay to this issue.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
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 same technical skills. I remember one company in particular—a machine controller company on 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 controller up, or how to stop it in case of an emergency—critical details that any neophyte user should expect to find in a manual.
