A Writer’s Prerogative

The previous post explained the skills that a writer should have to prepare effective documentation. But what about the concepts? 

Conceptually, what should a technical writer have in mind while preparing user documentation? I was thinking whether what should be a writer’s thought process before writing about technology. Thus, this post happened.

Following are the areas which may help a technical writer conceptualize effective technical documentation process:

• Visualize your audience: Understand and if possible visualize your readers and their needs, attitudes, and most importantly, their awareness of the subject matter. Adapt your writing to these factors and their technical skills. Understand in advance what the audience would (or should) think when they have completed reading your document.

• Understand the Context: Know the context in which the readers might perceive or judge your writing. Some audience may view the information you have developed from a critics’ viewpoint. For example, if you generally use American English and the audience is British, they are extremely particular about the subtle differences between the English used in America and England. So, shape your writing according to it and always understand the scenarios.

• Formulate a sound writing plan: Good writing is a result of a sound process that includes gathering correct information, brainstorming and categorizing thoughts. The typical process would include analyzing information, creating drafts, editing them, and revising information if it does not fit into the flow of the document. Even great writers might not get a perfect write-up in a single try. You will have to spend time and keep revising your content until it is in sync with the requirements. Even if you are piled up with multiple tasks, try to invest time in composing content step by step: analyzing, drafting, editing and revising each assignment. It will reduce your efforts eventually.

On the whole, the above points provide you with a pre-writing analysis. If you comprehend these aspects well, you can clarify many of your initial doubts and save yourself some quality time on rework.  For details about basic technical writing skills, see 7 – Habits of a Highly Effective Technical Writer.

Principles for Effective Technical Communication - 2

You, as a writer should able to understand and anticipate the challenges listed in the previous post.  Your job is to make your users’ tasks easier. So, you can address the challenges using these seven writing guidelines.

7 - Habits of Highly Effective Technical Writer

1. Analyze the subject thoroughly
2. Group information wisely
3. Guide the user and help them find information
4. Elaborate or compress the information scope based on importance
5. Be precise while using words
6. Be crisp and clear with your information
7. Review, review and re-review your information 

1.  Analyze the subject thoroughly.

• Before you start writing a topic, you must have a knowledge base in your mind. You must gather information from existing documents. If possible, you must talk to subject matter experts and study the product extensively.

2.  Group information wisely.

• Group similar topics together
• Each section should be complete and should have an introduction, body and conclusion
• Order the information groups appropriately

            > If you are describing a process, list the steps chronologically

            > To explain something, move from general to specific points
            > To document a project try ordering by problems-methods-solutions
            > To persuade, order your arguments from most to least significant

3.  Guide the user and help them find information.

• Give introduction to let user know what should they expect
• Give summary of what you have covered in the topic
• Use headings, lists, and other formatting devices to make the information accessible.
• Highlight appropriate areas using Note, Tip and Warning statements.

4.  Elaborate or compress the information scope based on importance.

• If you are explaining a complex process involving multiple steps, it is worth adding elaborate steps. Whereas, if you are writing about a commonly used procedure you may write the steps concisely.

Note: Understand your audience before implementing this step.

5.  Be precise while using words.

• Use technical terms correctly and appropriately for the audience. Avoid unnecessary jargon.
• Avoid using vague and ambiguous words
• Avoid lengthy noun phrases
• Avoid using adverbs like actually, apparently, basically, briefly, certainly, clearly, conceivably, confidentially, curiously, evidently, fortunately, hopefully, ironically, etc

6.  Be crisp and clear with your information.

• Avoid wordy phrases: Keep the information simple and understandable. Some wordy phrases might sound "smarter" but they can make documents long and can annoy readers as well. Few examples,

Wordy	Consice
Adequate number of	Enough
At all times	Always
Except when	Unless
For the purpose of	For
In an effort to	To

• Combine short sentences wherever possible. Reconsider breaking a long sentence into short meaningful sentences.
• Generally, favor the active voice over the passive voice. Active sentences are generally shorter and direct. Active voice reduces ambiguity and conveys your message clearly.

   
7.  Review your information repeatedly.

• Review content for errors like formatting, spelling, punctuation, and labels (tables and figures).
• Proofread! Allow some time (even if just a few hours) to pass between drafting and revising the document.
• Edit in parts. Take short breaks while reviewing as well.
• Prepare a checklist based on your review mistakes and observations.

Though, this list is not complete, it  highlights some of the common areas where a technical writer can improve and thereby deliver quality documentation to the customers. For more information on challenges faced by beginners, see Challenges of an Aspiring Technical Writer.