Effective Technical Writing Guidelines - 2

1. Writing Guidelines: A Closer Look

   
   

   1. Organize information logically
   • Group similar things together.
   • Order those groups appropriately.
     The "appropriate" order depends on the situation. For example:
   • 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.
   
   
   2. Provide cues to help readers follow and find information.
   • Use headings, lists, and other formatting devices to make the information accessible.
   • Use forecast statements to preview what is ahead. Use summary statements to review what you've covered.
     In this example, the writer has previewed the specific points that her proposal will cover and the order in which she will discuss them:

   "This circuit can be broken into four blocks:

   o The square and triangle generating portion

   o The JFET-based circuit

   o The module that uses the square and triangle waves to form a saw tooth

   o An amplifier with adjustable gain"

   3. Make the proportion of space you give to any information reflect the relative importance of that information.

   4. Choose words precisely

   o Use technical terms correctly and appropriately for the audience. Avoid unnecessary jargon.
   "We will use different capacitors in order to cancel out the glitch."

   
   

   o Avoid vague words.
   "The circuit experienced some difficulties."
   Which circuit? What is a difficulty?

   
   

   o Avoid ambiguous words and phrases (especially "this" and "it")
   "When the square wave is negative, the inputs to the op-amp are grounded, and the input signal is inverted. This produces a double-frequency saw tooth of the same amplitude as the input."
   What's "this"—a negative square wave? grounded inputs? an inverted input signal? all of these?

   
   

   o Use strong verbs.
   This example obscures the "real" verbs:
   "The component count of the circuit is kept minimal with the use of an integrated circuit (IC) JFET operational amplifier in the input stage."

   
   This revised version features stronger verbs:
   "The design uses an integrated circuit (IC) JFET operational amplifier in the input stage to minimize the number of components." [emphasis added]

   
   The following example suffers from a weak verb and from wordiness:
   "Proposal: The proposed Frequency-to-Voltage converter is part of a three person collaboration to build a circuit in lab that, ideally, could be employed, for example, in the transmission of touch tone phone conversations."

   
   The writer also uses a cumbersome noun phrase ("employed . . . in the transmission of") to express the real action (simply to "transmit"). Also, notice the unnecessary phrases ("ideally, could be employed," "for example"). As revised:
   "Three students propose a collaborative project to build a Frequency-to-Voltage converter that could transmit touch tone conversations."

   5. Write Clear, Concise sentences

   o Avoid wordy phrases.
   Some wordy phrases can seem to sound "smarter" than simpler ones. But wordy writing can make documents excessively long and frustrate a reader. You can often replace a bulky phrase with something more concise. Paring down such phrases can substantially shorten a long document without compromising your meaning.

   
   

   Wordy	Concise
   a majority of	Most
   a number of	few, many
   subsequent to	After
   in order to	To
   in view of the fact that	because, since
   based on/due to the fact that	Because
   during the course of	While
   for the purpose of	For
   with regard to	about, concerning
   in the event that	If
   so as to	To
   take into consideration	consider
   have the capability to	Can

   
   

   o Combine short, choppy sentences.
   "We found a solution. The solution can be displayed on an oscilloscope."
   Revised:
   "We found a solution that can be displayed on the oscilloscope."

   
   

   o Generally, favor the active over the passive voice.
   In the active voice, the subject of the sentence ["design"] performs the action ["offers"]:
   "This design offers more advantages."
   
   

   In the passive voice, the subject receives the action. Passive sentences are usually longer, more complicated, less direct than active ones. Writers sometimes favor passive voice because it can seem to sound more scientific or objective than the active voice:

   
   "In this design, more advantages are offered."

   
   As this example shows, active sentences are usually shorter and more direct than passives. Use the active voice unless you have a good reason not to.

   6. Review drafts for problems in format, spelling, punctuation, units of measurement and labels for figures. Proofread! Allow some time (if only just a few hours) to pass between drafting and revising the document.

   
   

   o Edit in Stages

   o Make a first pass to see if the organization is good and the information is correct. (You might even make an outline from your first draft after you've written it, to check whether the sequence is logical.)

   o Make another pass to check phrasing and spelling.

   o Reading aloud can help you spot any wording that needs revision.

   o Use your word processor's spell checker, but remember that it will not catch all errors. You must also proofread.

   o Learn from past mistakes . . . and past successes. As you write each new assignment, remember the comments your past writing has received. Keep these in mind as you revise.