Six Ways Technical Writers Create Poorly Written Manuals and Some Fixes

Rather than trying to explain all the right ways to do something, it’s oftentimes more helpful to explain the wrong ways to do things in order to prevent those pitfalls.

One of the common complaints about technical manuals is how poorly they are written. When people buy a new product, they hope they can get it to work out of the box. But, many times they must resort to a user manual. Merely having to look at documentation isn’t something people necessarily want to do.

If they can’t find the answers, or get impatient looking in the manual for one, people often call technical support. The costs are high. Here’s an excerpt from

“For many end users, bad documentation amounts to nothing more than an inconvenience and possibly a poor impression of the company,” said Wier. “But for companies, the results can affect the bottom line in terms of overloaded help lines, reduced revenues from dissatisfied customers who won’t come back, and increased liability.” [1] Basically, poor manuals create poor revenue, bad PR, and resentment.

Here are six sure ways that will screw up a technical manual.

1. Assume the end user knows more than they do about the product.

owners_manualFirst of all, the end user wouldn’t be reading your manual if they had all the answers. Furthermore, manuals (and your tech writing job) wouldn’t be necessary if all consumers knew how to intuitively operate or install anything they purchase.

You, the writer, assumes the responsibility to transfer specialized knowledge of a product or procedures from the R&D/engineering department to the consumer in a way that the end user can understand.

Product information:
Include all that the end user should know: product data or technical specifications (especially if it’s electronic or mechanical), help-line/tech support number, where to get replacement parts, quick start guide, overview or introduction of product (with diagram[s], if necessary, with button features, location, etc.), warranty, title, abstract, revision history, and so on. Much of this can be included on-line, or the company may not want to disclose some of this information. Either way, it’s more convenient if the information is readily available in front of them when they’re reading the manual.

Product procedures:
Don’t cut corners when writing step by step instructions. Put yourself in place of the end user. Think of the process. If possible, have the product in front of you when you use it. List step by step what to do and what to be aware of.

For example, if an electrical box must be opened for installation or replacement, inform the reader to perform all functions in a safe manner such as shutting off the main power at the GFCI or fuse box and possibly securing it with a lock while the system is being worked on.

It’s also helpful to include shortcuts and tips not obvious in the process. A simplified example is in installing a computer card: “To facilitate installing the Acme video card, first remove the left rear side panel to remove cables A and B.”

Tip: Talk to people on the assembly/manufacturing floor to find the best process of how to install components in a product. Be aware that you may have to alter or include different versions of the installation/removal procedure if a product design changes considerably.

Use what other people know. Much of the advice I got was from people on the assembly lines. Engineers, electro-mechanical personnel, and customer service/field technicians within your company have a wealth of information they can share on ways to improve repair and replacement procedures for your technical manual. Be sure to speak with their lead/supervisor before taking up their time. Many of these people have their own schedules to keep.

2. Be lax about warnings, cautions.

sunshade4In America, we’re surrounded with warning labels that defy common sense: “Never drive your vehicle with a sunshade in your windshield.” But the truth is, companies have gone label crazy in order to prevent litigation. Either way, we’re stuck with the label/caution craze.

Most tech writers usually fall back on previous tech manuals to find FAQs, warnings and cautions that their company has used. If not available, boiler plate documents and templates can be found on-line. For example, if up-to-date warnings and cautions relating to latest electrical codes are needed, information can be found on websites such as Underwriters Laboratories Safety Standards, National Electrical Code (NEC), National Electrical Manufacturers Association (NEMA), or ROHS (Restriction of Hazardous Substances Directive [EU]).

Safety warnings: Oftentimes have to state the obvious, and have to repeat warnings throughout the text. “Unplug the main source of power before….”

Warning pages should be updated appropriately if the equipment upgrades warrant it. If that’s the case, it’s a good idea to run your concerns past engineering and management.

3. Obfuscation: Use words that most end users doesn’t understand.

obfuscation_words1Jargon is specialized technical terminology confined to a specific group of people. If you’re writing a diagnostic and repair manual for your company’s field technicians for example, they’ll understand your jargon simply because it’s the company’s lingo. But if a writer starts using jargon in manuals written for the general public, they’ll probably not understand what you’re referring to.

Consumers shouldn’t have to guess what’s being said. Simplify your jargon for the end user. If a technical word must be used, either explain that word within text or provide a glossary. Here’s an example using the term Rated Voltage in a product specification sheet: “Rated Voltage is the maximum voltage at which an electric component can operate safely for an extended period of time. Do not exceed the Rated Voltage.”

By the same token, if you use acronyms or abbreviations, define what they mean when they’re first used.

4. No illustrations. Keep it all text.

words-only1Unless you’re Charles Dickens and can create mental, detailed images using only words, use illustrations. Sketches are good. CAD/CAM illustrations are almost essential to show objects in exploded views or cutaway illustrations. And, if photos are used, be sure they are well lighted, uncluttered, and clear. We’ve all seen manuals that have grainy, poorly focused photos. That’s not acceptable. It never is when marketing a product.

It helps to have a team of graphic artists that you can turn to for help. If you work solo, take time to learn Photoshop, GIMP, or another image manipulation tool. If simple tools like IrfanView work for you, fine.

Don’t forget to label the photos/illustrations with clearly identifiable titles or references in some ordered fashion. If there are many illustrations, consider adding a separate table of contents for them.

5. Ignore highlighting important things.

attention-1315471All text written in a manual should be considered important; otherwise, leave it out. But some text should be made more prominent at times. Bold text, attention symbols (exclamation marks in triangle, for one), and other attention getting techniques breaks the cadence of the reader. It causes them to slow down and take notice of why that symbol was put there.

Feel free to use a simple attention icon (light bulb, perhaps) to offer a valuable insider’s tip that can help a user in a specific process of assembly or repair. Don’t overuse the use of highlighting or symbols, though, as they become less meaningful.

Most important, be consistent with any attention getting icons or fonts. A page near the beginning of the manual devoted to describing the icons/fonts helps keep them clear and consistent. Include that legend page into your table of contents for quick reference. Plan to refine and keep that icon/font consistency into your next manual(s) to brand the look of your product, company, and manuals.

6. Don’t bother with a table of contents or index.

the-file-1One of the worst violations I’ve seen is to not have a table of contents (TOC) in larger technical manuals, or the TOC is poor or incomplete.

This must be said: End users don’t read manuals, they skip through them. People don’t like reading technical manuals, including yours or mine. To them it’s a chore. It’s something that needs to be done to gain information. Most likely they go to the table of contents (or index), find their topic, and pray that the answers they’re looking for are written in a lucid, logical sequence without poor grammar and typos.

A well, thought out table of contents and index makes for a good user experience.

TOC’s should be included once a manual gets over 10 pages in length. An index should also be added, if possible. A TOC and index simply help the reader get in and out of the manual as quickly as possible.

Powerful desktop publishing software such as FrameMaker and InDesign can regenerate a TOC and index on the fly once they’re set up. Both a TOC and index takes minutes to set up. There can be a learning curve on how to set them up and to use style sheets, but the result is well worth adding to your repertoire of skills.



Leave a Comment