Technical Writing Tips

When writing technical documentation, it is important to be clear and concise. Here are some helpful hints from the technical writers and technical editors of New England Writers Group.

Arrange your material logically.
Information is most helpful to readers when they can easily find the information they need.

• Always begin with ideas the reader can readily understand.
• Use transition words like however and furthermore as signposts.
• If you must present difficult material, go one step at a time.
• Arrange the format to give the reader every possible "handle" on the material—move important information to the top, put similar ideas together, use headings, etc.

Be accurate.
Always check your facts. Your writing must not allow for various interpretations. Anticipate questions your audience may have by defining all terms that may be confusing and explaining each point adequately. Have a colleague or friend check your work for accuracy.

Be concise.
Use concrete terms instead of abstractions, jargon, and generalizations. Make every word count. Keep the average sentence length under 20 words. The following extraneous phrases should be deleted from every sentence:

• Due to the fact that
• It has been shown that
• It is worthy of note
• It is recognized that
• It is found that
• It has been demonstrated that
• It may be mentioned that
• It must be remembered that
• It is the intention of this writer to
• It may be seen that

Keep related elements together.
Place modifiers as close as possible to the words they are intended to modify. Misplaced or dangling modifiers can be humorous or confusing.

Example:
Confusing: I borrowed an extension cord from my neighbor, ten feet long.
Better: I borrowed an extension cord, ten feet long, from my neighbor.
Best: I borrowed a ten-foot extension cord from my neighbor.

Use vigorous language.
You can make your writing more vigorous by:

• Avoiding heavy-duty nouns (nouns made by adding endings to verbs and adjectives).
• Using the active voice, rather than the passive.
• Making abstract ideas into concrete statements.
• Avoiding overuse of prepositional phrases.

An important element of vigorous language is the active voice. In the active voice, the subject of a sentence does the action (Bob throws the ball); in the passive voice, the subject receives the action (The ball was thrown by Bob). Although both voices are grammatically correct, the active voice is usually more effective because it is simpler and more direct.

Use examples to support your points.
When writing directions, make sure your reader "sees" the steps by organizing the material logically and using plenty of examples and illustrations (in words and graphics). When writing persuasive documents, put your main argumentative point up front and use examples to support the points you make, introducing these points with strong topic sentences.

Do a final check of spelling and grammar.
Even the best writers make grammatical and spelling errors. Ask a colleague or friend to proofread your work before printing the final copy. Always run your software's spell-check utility.