Common Mistakes

Make a Plan
A major mistake that novice technical writers make is working without a plan or outline. Lack of planning leads to more work later on in the project. A good plan includes:

Good technical writing is organized, easy to follow, and free of errors. The technical writer understands the product. If the writer constructs sentences without understanding the content, then the reader will not understand, either.

Use Templates
Another common mistake novice technical writers make is failure to use a template. Templates streamline the work process and save valuable time. Templates allow the document's reader to focus on the content. Variable design that does not use a template is inconsistent, distracting, and unprofessional looking. Templates do need to be unique to the project; it is not a good idea to use a universal template for every document. Ask your client if the company uses a house style, so that your work is consistent with your predecessor's.

Construction

  • Write every step clearly. List the necessary equipment first, followed by the directions in consecutive order.
  • Be specific. Avoid ambiguity or double meanings. Do not write something vague, such as:
    • "It will take some time for the dial to illuminate."
    • Instead, write: "The digital numbers on the right side of the channel selection screen illuminate in 5 - 7 seconds."
  • Write in the present tense imperative whenever possible. Avoid past, future or conditional tenses (using the word 'should'). For example:
    • Correct: Insert Tab A into Slot B.
    • Incorrect: You should try to insert the tab into the slot.
  • Use active voice. Avoid passive voice. For example:
    • We made mistakes.
    • Mistakes were made.
  • Do not use contractions (don't, won't, shouldn't, can't).
  • Avoid gerunds where possible (any word ending in 'ing').
  • Remember that not every reader is an American. English may not be your reader's first language. Use a formal style of writing that is free of jargon or local colloquialisms.
  • If a specific instruction could cause injury if performed incorrectly, place a warning in a text box before that instruction.
  • Never assume the reader has technical knowledge. Explain even elementary steps that seem obvious to you.
  • Name and archive the files according to the company standards for future retrieval.
  • Do not manually construct or hard code the Table of Contents, index, cross references, footnotes, and caption numbers. Allow the software to do this electronically, so they can be updated automatically.

Technical Writing - Main