Common Pitfalls in Technical Documentation

The purpose of technical communication is to instruct and explain. Understandably then, accuracy is paramount.

Yet subtle mistakes in writing quality can undermine the strength of your message. Readers naturally develop trust in companies whose technical documentation is rock solid. Likewise, they question the value of a company’s product when its technical documentation is poorly written or poorly translated.

Obviously, technical documentation should be free of spelling and punctuation errors. But let’s look at a couple of other common mistakes found in technical documentation:

Unnecessary Quotation Marks

I once worked for a woman who pronounced the word intranet with a elaborate stress on the middle syllable. In-TRAH-net. Every. Single. Time.

While it’s respectable that she wanted to say the right word, the overemphasis in her pronunciation reeked of uncertainty. Perhaps she misused the term once, was corrected, and vowed to never make that mistake again. To us, it sounded like she didn’t really know what our intranet was, only what someone told her to say about it.

In writing, the use of unnecessary quotation marks adds emphasis where it shouldn’t exist.

Nothing expresses a total lack of confidence like slapping a set of quotation marks around a technical term!

Bad: With XYZ Software, your data is kept secure in the “cloud”, where you can conveniently access it from anywhere.

Why the quotes?? Is cloud computing an unfamiliar concept? Did someone tell you to use the term, but you’re not comfortable with the meaning? Maybe XYZ Software is jumping on the bandwagon, without a firm grasp of their own technology?

Good: With XYZ Software, your data is kept secure in the cloud, where you can conveniently access it from anywhere.

This is much better. It exudes sureness, and readers can trust that XYZ Software knows what they’re talking about. So, skip the quotes for technical terms, product names, and trade show names. Quotes should only be used to denote exact words that were said or written.

Inconsistencies

Another common mistake I find in source language and translated technical documentation is inconsistent word use and capitalization. Like unnecessary quotation marks, these inconsistencies reflect poorly on the brand and product being described.

For example, in instructions on using a mobile app, don’t use tap and press interchangeably. Pick one and stick with it!

Another example is capitalization, particularly in proper names containing one or more uppercase letters in the middle of the name. Think PayPal, which is so often incorrectly written as Paypal, even by otherwise respectable companies. It’s simply wrong, and people notice. You wouldn’t write AirBus or MicroSoft. Proper capitalization matters! It reflects your company and its knowledge of the industry.

These inconsistencies and others can be avoided by implementing a style guide to define standards for spelling, punctuation, formatting, and word use.

Companies with documentation in multiple languages should have a style guide for each language. TechWhirl offers some great tips on building a style guide.

Last Word

Remember, your technical documentation is a direct reflection of your company in all the languages of your customers. Aim for excellence!