Technical Writing ToolBox

Few weeks back I talked about three external factors that gives birth to inefficient documents.  Writers either have no or very less control over these factors. However, this is not always the case. In fact, usually a writer makes documents inefficient if they fail to remove common writing mistakes from their work. Let’s look at seven  factors that cause inefficient writing even when the content is technically accurate and the grammar is perfect:

1. Uninviting Appearance

I’ve always believed that presentation of information is as important as the content itself.

Let’s take an example of visiting a restaurant for dinner. Let’s visit three different restaurants: A, B, and C in three consecutive nights.

1. In the first night, you visit A. The quality of food in A is great but the dishes are dirty, the table-cloth has spots and the waiter face is almost like he is about to kill somebody. In other words, content is great but presentation is not. Will you visit such a place again?

2. In the second night, you visit B. The waiters at B are extremely polite and helpful, the dishes looks great and there is great aroma in the place. However, the food tastes really bad. In other words, presentation is great but content is not. Will you visit such a place again?

3.  Disheartened by your last experience, you almost drag yourself to visit C. The food smells great, the waiters are professional and helpful and they even suggest popular dishes and gave you a first visit discount. The food is awesome and you almost ate your fingers while eating that apple pie. In other words, presentation is great and so is the content. Will you visit such a place again?

When you write information, you need to write great content and also need to make it look attractive so that you get repeat business, just like the third restaurant C did.

2. Inadequate Information

Having more (or less) information than required is probably the top reason of inefficient writing. Writers often do not equate audiences needs and create documents which have either too much or too less information which does not meets their audiences requirement.

Fault does not entirely lies at writers end though. Parroting Engineers and Management folks often cause this problem.

Being an Engineer myself,  I hate to criticise Engineers and other SMEs for adding too much information in the documents. As a writer who has managed several documentation projects, I hate to criticise people from higher management to offer very less information to a writer. When a writer performs a cosmetic surgery of the source information received by SMEs and management, S/He fails the purpose of writing an efficient document.

3. Confusing Structure

Another prime reason for inefficient writing is to use a confusing structure in their documents. Though by adopting a structural writing paradigm like DITA or Information Mapping, they can solve this problem to some extent but writers still prefer to continue writing their brilliant work in a confusing structure.  As a result, readers get confused instead of getting informed.

4.  Irrelevant or Uninterpreted Information

With a desire to provide more information, writers often add irrelevant information in their writing without thinking if the new information will be useful to their audience or not.

I often divide the information I collect for my work into three mental zones of Must Have, Good to Have and Not Required blocks and weed out the not-required and parts of good-to-have information. This makes the document a bit more efficient and easy to read.

 5.  Unnecessary Jargon

Saskatchewan Transportation Company (Photo Credit: Wikipedia)

People often forget that terms which makes perfectly sense to them may not be as clear to others. For example, the term double-double is commonly used in the famous Canadian coffee stores of Tim Hortan which means two portion of sugar and two portion of milk in the coffee. Now imagine using the same term in a cafe in France. Will it convey the same meaning as it does in Toronto?

Another drawback of using jargon is that people may understand it differently based on their perceived context. For example, let’s take example of STC. While for most of technical writers out there, STC brings back images of conferences and meetings of technical writers. However, if your audience is not technical writers then STC could mean Saudi Telecom, The Society of Toxicology of Canada, or The Saskatchewan Transportation Company based on their location. Choose your words carefully!

6. No Visual Aids when Readers needs them

A lot of writers do not believe in the saying “A picture is worth 1000 words” and often write long paragraphs full of numerical data that could be easily replaced by pie charts. Why write 20 steps when a  flowchart could explain the same level of information in just one diagram?

7. More (or less) words than required

People often equate conciseness to short sentences. However, short sentences itself doesn’t guarantee conciseness. The sentence may be short but still unclear. Technical Writers value conciseness since it reduces reading time and often results in lower production and translation costs. Having more or less than adequate  words is another common reason for inefficient writing.

As William Strunk in his classic text The Elements of Style tells us “Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.”

As a writer I often struggle to make my writing free of these seven writing sins. I’d love to hear from you about effective ways of removing these seven reasons of inefficient writing from a document. I’m awaiting your comments (and so does the waiters and staff at Restaurant C).

Image courtesy of FreeDigitalPhotos.net