Six Simple Steps To Clearer Technical Writing

Effective technical writing is taking complex information and putting it into simple language that all your audiences are able to understand. Many of us who write technical documentation often get caught up in the content, forgetting about our target audiences. In the end, we end up with a document that few people are able to understand.

There are a few simple steps that you should keep in the back of you mind when creating technical documentation. By following these simple steps, you have a much better chance of ending up with a document that readers can understand.

  1. Write in an active voice

    • Write in an active voice, not a passive voice
    • In an active voice, the subject of the sentence performs the action; in a passive voice, the subject is the recipient of the action.
    • Subject – verb – object
    • Passive verbs are longwinded; make sentences sound “wordy”
    • Passive sentences usually include a form of the verb “to be”, such as, “am”, “is”, “was”, “were”, “are” and “been”
    • Use Spelling & Grammar feature of Word to track your use of passive voice
  2. Use familiar words
    • Use familiar words instead of complex words
    • Complex words are also referred to as technical jargon
  3. Keep sentences short
    • 15 – 20 words per sentence
    • Break long, complex sentences into shorter, simple sentences
    • Eliminate unnecessary words (filler words) to reduce sentence lengths
  4. Avoid wordiness
    • Avoid using redundant words and phrases
    • Use concise words instead of wordy phrases
  5. Use bulleted/numbered lists
    • Use bulleted lists to create separation between similar ideas
    • Use numbered lists for steps and sequences
    • Limits the number of items in a list (six to eight)
    • Properly introduce each list with a complete or incomplete sentence
  6. Define acronyms
    • Spell out each acronym on first use

[tags]technical writing, writing how to[/tags]

Article Written by

  • steve

    Diane,

    I enjoyed reading your article concerning Six Steps to Technical Writiing.

    Being the son of a professional writer, I enjoy reading about and improving my own language skills, as I did not inherit my father’s abilities.

    The link to your article above followed one of the many emails I receive regularly concerning a rich relative of a stranger that has died in a foreign country and they need my assistance to obtain the inheritance. I read these knowing of course that they are all phoney, but I always obtain a hearty laugh because the style of the English is so poor. If I did know any better, it almost appears they are going out of their way to make these letters as humorous as I find it. My most recent letter started out stating “I am sure you are both delighted and surprised to hear from me, I wrote you because you express both sincerity and transparency in our previous communications . . . ” As this letter was completely unsolicited, yes I was surprised, however, not delighted to receive it, and the last time I looked in the mirror, I was rather opaque, so I am not quite sure what the comment about transparency meant. But in any event, I think it would make a great coffee table book or weekly article to publish these letters, and suggest ways to improve them in case you should ever run out of legitimate things to right about.

  • Sherman E. DeForest

    I have some comments:
    First, the passive voice exists for a reason. Second-rate technical writers tend to overuse it, but that does not mean we should avoid it at all costs. Fam

  • Sherman E. DeForest

    Maybe this time. I keep getting interrupted.

    Excellent piece. I have a few comments.

    Passive voice exists for a reason. Second-rate technical writers tend to overuse it, but that does not mean it should be eliminated [sic].

    Define “Familiar Word” carefully the written language is different from the spoken one. As a small example, good technical writing avoids the common contractions, which are acceptable and expected in speech.

    Two new comments: (1) Writing is stronger is the author avoids using the indefinite “to be” as in “There are a few simple steps…” (2) As a graduate student, I was warned (better: My adviser warned me..) to avoid personalizing my writing by displaying myself as the subject as in “The results of the experiment indicated to us…” I rebelled at the time and still think that limitation is artificial.

    Sherm

  • bob gailer

    Nice article. Many writers could benefit from it.

    Please give examples – some might find it hard to map your comments to their writing.

    I can’t always use familiar words in technical writing. To bridge the gap provide a glossary.

    More guidelines:

    Use terms consistently. You are not writing a novel. One manual I read used “output”, “library”, “output library” and “library output” in one paragraph to refer to one file!

    Provide a thorough index. Anticipate the various search strategies readers might use, and have entries for most or all of them. Include an entry for the first page of each chapter and section.

    Regarding language reference manuals:
    – state all effects of language elements
    – use meaningful terms in parameter lists
    – list all errors a command might raise
    For many examples of violation of these rules see Visual Foxpro documentation.