Six Ways Technical Writers Totally Screwed Up Technical Manuals

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.

A common complaint about technical manuals is how poorly they’re written. When people buy a new product (the end user), they expect 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, 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.

First 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 purchased.

You, the writer, assume 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. Whether on paper or digital, correct information is essential to end users reading your manual.

Product procedures:
Don’t cut corners when writing step by step instructions. Think of the process. Put yourself in place of the end user. 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 worked on.

Include shortcuts and tips not obvious in the process. A simple example is installing a computer card: “To facilitate installing the Acme video card, first remove the left rear side panel to remove cables A and B.”

Keep up on product design changes. If the design changes considerably, you (as a tech writer) may have to alter or include different versions of the installation/removal procedure depending on the model.

Tip: Use other people’s  knowledge and experience. Talk to workers on the assembly/manufacturing floor to find the best process of how to install/disassemble components in a product. (They’ve done it hundreds of times.) Much of the advice I got was from people on the assembly lines. Be sure to speak with their lead/supervisor before taking up their time. Many of these people have their own schedules to keep.

Engineers, electro-mechanical personnel, and customer service/field technicians within your company also have a wealth of information they can share on ways to improve repair and replacement procedures for your technical manual.

2. Be lax about warnings, cautions.

In 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.

Tech writers often use their company’s boiler plate “standardized” FAQs, warnings and cautions. If these aren’t available, boiler plate documents and templates can be found on-line and can be modified per company requirements. For example, if up-to-date warnings and cautions relating to latest electrical codes are needed, there are 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 you 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.

Jargon 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, the end user probably won’t 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 of phrase must be used, either explain it within text or provide a glossary. Here’s an example of explaining 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.” Simple enough.

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


Like what you’re reading? Consider How to Write Better Technical Manuals.


4. No illustrations. Keep it all text.

Unless 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. If photos are used, be sure they are well lighted, uncluttered, and clear. There’s no excuse nowadays of using grainy, poorly focused photos, especially 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.

All 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, for example) 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.

One of the worst violations I’ve seen is that a table of contents (TOC) is missing, 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. It’s a chore, yet it’s something that needs to be done to gain information. Most likely the end user goes to the table of contents (or index), finds their topic, and prays that the answers they’re looking for are written in lucid and a logical sequence without poor grammar and typos.

TOC’s are recommended 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, which creates a better user experience.

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. Of course there’s a learning curve on how to set them up–just as you learned how to use style sheets, and is well worth adding to your repertoire of skills.



Posted in Home.

Leave a Reply

Your email address will not be published. Required fields are marked *