top of page
Image by Leone Venter

The golden rules of technical writing

Updated: Feb 16

The purpose of technical documentation is to inform the reader about something she needs to know about a product, or to guide the reader through the steps of actions she needs to perform. How well the documentation does this is dependent on how it is written.


Written by: Mari-Ann Gripmark


Remember, you cannot please everyone! The most important reader to please is the end user of the product that your documentation describes or instructs about. Below are a number of very important golden rules to follow.

Two people standing by a huge list of rules. One is pointing at the list, and the other is pondering the rules.
Image by pch.vector on Freepik

Golden rules of technical writing:

  • Focus on the reader

    • Who is she? Does the user have a specific role in a company, or is she someone who has bought a product for personal use?

    • What info does she need? What does the user need to accomplish in her role or purpose using the tool you’re writing an instruction for?

  • Keep it simple

    • Use short, simple words and short, clear sentences.

    • No repetitions or redundant information.

    • No beautiful language or personal touch.

  • Make it impossible to misunderstand

    • Be specific.

    • Do not use synonyms.

    • Use the correct terminology.

  • Address the reader directly

    • Use active voice: YES: “You can change the configuration”. NO: “The configuration can be changed”.

    • Use imperative: YES: “To turn on the machine, press the On button.” NO: “The machine can be turned on by pressing the On button”.

    • Avoid “should” and “shall”: YES: “Do a backup”. NO: “A backup should be done”.

  • Do not mix description and instruction

    • If a descriptive part is needed, put it at the beginning.

    • Make it clear to the reader what she is supposed to do.


Summary: Focus on the reader, keep it simple and concise, be specific, use an active voice, and separate description from instruction.


Our advice to you: There are more aspects of technical writing that can be considered, depending on what kind of document you’re producing and the expected life cycle of the document. But by following these rules, you will be standing on a solid base producing really good material that will be helpful to the reader and also easily translated.


A woman laying on the floor with her long hair spread out, surrounded by pens, pencils, crayons,a scissor, noteboks and tape measure.
Image by Wix


Kommentare


  • LinkedIn
  • Instagram
  • Facebook
bottom of page