Effective Technical Writing Guidelines - 1

In my last post I had explained in brief, the important points to be taken care of while writing technically. This post will explain the methods for effective technical writing.

Let us first understand the mistakes that we as Technical Writers and Software Programmers are prone to making. Usually professors of technical writing and senior staff in the organization are concerned with some very common mistakes that we practitioners of technical writing keep repeating.

• Unclear purpose or context
  "At the start, I don't know why I'm reading the report. I don't understand how the specific information I'm getting fits into a larger situation. Does the writer know why I requested this information?"
• Baffling organization or logic
  "I don't understand where the writer is going or why I am getting one piece of information before another. I can't figure out how idea A leads to B and how A and B relate to C or D."
• Lack of clear conclusions
  "When I finish reading, I want to understand why the information is important to me. I want a good answer to my question, 'So What?'"
• Too much or not enough detail
  "The writer spends too much time discussing unimportant aspects and not enough time on what is most significant to me. The emphasis is misplaced, maybe to hide what the writer doesn't know."
• Muddled sentences, garbled expression
  "Individual sentences are difficult to untangle—wordy and ungrammatical. I resent spending time on this report."
• Sloppy or imprecise use of technical terms and concepts
  "The writer does not understand the engineering terminology, or misapplies it, or inappropriately addresses it to a reader who is not at this technical level."
• Faulty mechanics
  "What a mess! The document has errors in format, spelling, punctuation, and units of measurement. Diagrams are labeled poorly or not at all."

Writers' Obligations

Our challenge, as writers, is to anticipate such objections. If we want readers to understand and appreciate what we write, we need to make their job as easy as possible. We can translate readers' complaints into three overall considerations and six specific writing guidelines:

Three Overall Considerations

• Consider your audience.
  Understand you readers' needs, attitudes, familiarity with the subject matter, and technical level. Adapt your writing to these things. Decide in advance what your audience should think when they finish reading your document.
• Consider the situation.
  Know the context in which your writing will be read and judged. Shape your writing to it.
• Develop a sound writing process.
  Good writing results from a process that includes gathering information, brainstorming and organizing ideas ("pre-writing") as well as drafting, editing, and revising. Don't expect your writing to flow out wonderfully in a single try. Although you are very busy, try to spend some time composing in stages: prewriting, drafting, and revising each assignment.

Six Guidelines For Effective Writing

1. Organize information logically.
2. Provide cues to help readers follow and find information.
3. Make the proportion of space you give to any information reflect the relative importance of that information.
4. Choose words precisely.
5. Write clear, concise sentences.
6. Review drafts for problems in format, spelling, punctuation, units of measurement, labels for figures. Proofread! Allow some time (if only just a few hours) to pass between drafting and revising the document.