Category Archives: Writing Style

Clarity in Technical Writing

Why is clarity in tech writing important?

Where your writing and product will end up if you do not write clearly.

Clear writing communicates exactly what you want to say. The ideas are organized and easy to follow. They create no questions or confusion in the reader’s mind. He or she does not have to stop, go back, and re-read a sentence to clearly understand it. Clarity is paramount.

The reader is confident of the authority of knowledge in the text. The words on the page do not draw attention to themselves or create doubt.

The Dangers of Fuzzy Tech Writing

Unfortunately, this is not always so. Fuzzy instructions that do not illuminate in user manuals or badly-worded procedures can frustrate and enrage a user. They may throw the manual into the garbage and curse the product as a rip-off. 

victim of bad writing

Clarity is paramount, and Strunk and White explained this beautifully:

Muddiness is not merely a disturber of prose, it is also a destroyer of life, of hope; death on a highway caused by a badly worded road sign, heartbreak among lovers caused by a misplaced phrase in a well-intentioned letter, anguish of a traveler expecting to be met at a railroad station and not being met because of a slipshod telegram. Think of the tragedies that are rooted in ambiguity, and be clear! When you say something, make sure you have said it. The chances of your having said it are only fair.


Confusing User Manuals = Bad Product

One thing we tech writers have to keep in mind — Most users do not distinguish between manuals and products.

Even this dude get confused sometimes.

A confusing manual equals a bad product and vice-versa. Who hasn’t chuckled at an IKEA’s user manuals and forgiven some of the products shortcomings (particle board shelves)? And, on buying a Macbook, would we not expect the documentation to be as simple and elegant as the computer itself?

Many user guides have beautiful layouts. Apple’s user manuals are artsy and elegant. Dyson’s are colorful and bold. Many online user guides flow smoothly on our computer screens or tablets. 

Yet, no matter how nice the guide looks, it must first and foremost be clear to the user.