The golden rules of technical writing

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.

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 important rules to follow.

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.
• Use a direct language: 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”.
• 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 a direct language, 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.

Written by: Mari-Ann Gripmark

Top illustration by: Styrka Media - Animerad F?retagsfilm