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.
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.
