COMPUTER SYSTEMS RESEARCH
Elements of Technical Writing
2005-2006

  • Good technical writing is clear
    1. "In fiction and other nontechnical writing, clarity is not necessarily the key to good style.
      Obscurity has its place in some forms of literature, but not technical writing, where
      comprehension is the chief concern. Technical writers succeed when their work is readily understood by
      the intended audience.

      For clarity:

    2. "Keep the writing short and simple.
      • Use small words not big ones. Keep paragraphs and sentences
        short. Whenever you can logically break a long paragraph into two shorter ones, do so.
      • Break the writing into short sections, each with a descriptive subhead.
      • Limit each section to one topic, theme, or idea.
      • Sentences, paragraphs, and chapters that express one idea are easiest to understand.
      • One of the most common writing mistakes is to cram too many thoughts into a single sentence or paragraph."
    3. "Avoid jargon.
      • One reason why readers may be unable to understand a particular piece of writing is that they do not
        understand one or more of the words being used.
      • Some technical terminology is valid and necessary. But too much technical jargon makes writing
        incomprehensible.
      • Remember, not everyone knows all the lates buzz words in your discipline or industry.
      • Your readers are busy people, more likely to put your report aside than to reach for a technical dictionary."
    4. "Present your story in a logical, orderly fashion, one step at a time
      • Technical professionals and other nonwriters often feel they have to tell every last detail in the
        sentence they're writing at the moment. The result is too much information in too short a space.
      • Although brevity and conciseness are desirable, it's better to spread your information out in a
        series of well-ordered paragraphs than to lump everything together in a jumble.
      • Too much description in a single sentence makes writing dense and difficult to read. Let the readers
        breathe a little by presenting points as bite-size tidbits.
      • If a particular piece of information is important but doesn't fit logically into the flow of your
        narrative, place it in a ssidebar or appendix."
    5. "Use visuals"
      • Certain information can be communicated more effectively in visual form than as narrative text.
      • For example: a diagram - shows how it is put together; a flow chart - show how it works;
        a graph - show how one variable changes in relation to another; a pie chart - shows proportions
        and percentages; a bar chart - shows comparisons among quantities; a table - shows a body of data;
        a structured diagram - show the components of a system and how they interrelate."