| I've seen it time and again. One of the most | | | | This problem often occurs when developing user |
| common weaknesses that I've seen in engineering | | | | documentation. Programmers and engineers |
| companies-indeed, an almost universal fault-is the | | | | frequently forget that their manuals are going to |
| lack of proper technical documentation. Some | | | | be 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's | | | | skills. I remember one company in particular-a |
| entire future can be made or lost based on the | | | | machine 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 that | | | | acronyms, undefined terms and seemingly |
| I've found to be particularly common when it | | | | random thoughts, with about a dozen procedures |
| comes to writing technical documentation. I'd like | | | | listed in no particular order. Their user |
| to share these thoughts with you, in the hope of | | | | documentation lacked such basic details as how to |
| preventing others from falling down the same | | | | start the controller up, or how to stop it in the |
| paths. | | | | case of an emergency-critical details that any |
| 1. Not having any user manuals | | | | neophyte user should expect to find in a manual. |
| Don't laugh. This may seem like a fairly basic | | | | A related problem is the failure to use proper |
| mistake-absurd, even-but it is surprisingly | | | | language. Consider the case in which many of the |
| common. I've encountered many companies that | | | | readers are not native English speakers-say, when |
| don't provide user manuals for their products, or | | | | marketing a product in Europe or Asia, or when |
| whose manuals are skeletally thin or years out of | | | | writing assembly procedures for foreign-born |
| date. In fact, I'd estimate that about half of the | | | | factory workers. In such cases, it may be |
| small engineering companies that I've encountered | | | | necessary to keep the language fairly simple. If |
| fall into this category. (Of course, one seldom | | | | this is not possible-say, when discussing complex |
| encounters this problem when buying off-the-shelf | | | | details that demand a great deal of precision-one |
| software or consumer electronics. Amongst | | | | can 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 his | | | | Either approach can be helpful in making complex |
| company didn't provide any user manuals with | | | | text a bit easier to absorb. |
| their products. In hushed tones, he said, "It's | | | | 4. Not being suitably graphic |
| because we don't make any money by writing | | | | It's undeniably cliché, but true nonetheless-a |
| manuals. It's not a money-making venture, so our | | | | picture 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, then | | | | diagrams will be much easier to understand than |
| he leaned closer and said, "We have lost so many | | | | one that is composed entirely of text descriptions. |
| customers because we don't have decent | | | | Some 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 when | | | | guides. Remember; no matter how sophisticated |
| manuals are inadequate or non-existent. What | | | | your readers are, they're still human. Even an |
| about the employees themselves? What happens | | | | intelligent, otherwise careful reader can accidentally |
| when a new engineer comes on board, and has | | | | miss some important detail, especially when |
| to learn quickly? Or what happens when existing | | | | pressed for time. |
| engineers need to familiarize themselves more | | | | 5. Not striving for excellence |
| with unfamiliar aspects of their product lines? The | | | | It's interesting to see how programmers and |
| user documentation, if properly written, can | | | | engineers can strive for excellence in many |
| provide a gentle and efficient way of bringing the | | | | aspects of their work, yet take the exact |
| up to speed. Without it, they will be forced to rely | | | | opposite approach when it comes to |
| more heavily on other engineers to educate | | | | documentation. "Who cares about wording |
| them, thus wasting the time of everyone | | | | anyway?" I've heard many engineers say. "We're |
| concerned. Weeks, if not months, of valuable | | | | not 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 documentation | | | | technically accurate." |
| It's not just the user documentation that | | | | This is an appallingly short-sighted view. Technical |
| companies fall short on. Internal documentation is | | | | accuracy is indeed important, but so are |
| frequently a casualty as well, as companies | | | | presentation and style. Few engineers would listen |
| scramble to release a product. In their haste to | | | | to a job applicant who shows up in a bathrobe |
| bring products to market, companies often let | | | | and slippers, or a litigation attorney who speaks |
| their internal design documents fall hopelessly by | | | | like 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 engineers | | | | customer!) to slog through pages of meandering, |
| are notorious for having lackluster communication | | | | poorly phrased text. Even matters as |
| skills, and that documentation is a task that they | | | | fundamental as spelling, grammar and proofreading |
| seldom enjoy. I've encountered many software | | | | are often treated as mere annoyances-piddling |
| companies, for example, whose software designs | | | | details that are worth nothing more than a |
| were an intractable mess due to their lack of | | | | cursory glance. |
| architectural documents, interface descriptions and | | | | (To my relief, I have not encountered any such |
| in-code comments. Sadly, I've seen similar | | | | attitudes 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, manufacturing | | | | about 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 have | | | | which I am always thankful. But I digress.) |
| either gone under, or have been teetering on the | | | | Remember: When writing for one's fellow techies, |
| brink. Almost invariably, lack of adequate | | | | one should bear in mind that they must often |
| documentation has been a major factor in such | | | | absorb voluminous amounts of information in |
| situations. | | | | scant amounts of time. When writing for laymen, |
| I always tell my bosses and co-workers, "I want | | | | one should make the text as gentle and easy to |
| to make sure that my work is darned well | | | | digest as possible, lest they become lost in an |
| documented. If I leave the company, or if I die in | | | | ocean of geekspeak. Either way, putting a little |
| a car accident, for I want to make sure that this | | | | extra effort into matters of elegance and style |
| company can march on without me." That should | | | | can make a world of difference. |
| be one of the prime reasons behind keeping | | | | I won't go into detail about what constitutes good |
| thorough documentation-to make sure that the | | | | writing technique, as that would be beyond the |
| company won't be crippled by any person's | | | | scope of this text. Suffice to say that a good |
| absence. | | | | programmer or engineer should make sure that |
| Unfortunately, many employees take the opposite | | | | his writing is readable and well-organized, and that |
| tack. They purposely scrimp on the | | | | it flows smoothly from one topic to another. |
| documentation, thinking that this will ensure them | | | | I 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 an | | | | another story about companies collapsing due to |
| engineer who documents well is worth far more | | | | non-existent documentation. A hopeless fantasy? |
| than another engineer who keeps his cards close | | | | Maybe. Still, I hope that some techies out there |
| to his vest. The latter may be essential in the | | | | will 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 | | | | |