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