10 Golden Rules
I came across a great article recently that outlines 10 golden rules for technical writing. Even though this is from a technical perspective, I think there are also some great takeaways for everyone, including you Marketing folks out there.
Back to Basics – The 10 Golden Rules of Technical Writing
I’m going to reprint the important points and rewrite them a bit below (yes, I’m plagiarizing) because it’s just that important, and because I’ve divulged my sources above. So no harm, no foul (Rule #11 might be to always reveal your sources).
1. Paper is Permanent
Own what you write and be responsible for it. Write correctly, proof read and edit the documents properly, and provide a proper content structure. Why is this important?
- Users judge the quality of a product or software based on the quality of documentation.
- Quality states the measure of accuracy (absence of errors), like typos, spelling, punctuation, incorrect data.
- Usability defines clear and accurate information.
- Is the content standalone?
- Can someone use it?
- Do you understand what you are writing?
- Is the information misleading or ambiguous?
#2. Know you Audience
Who is the user? It is essential to know who is going to use the document, including audience demographics. Take into consideration the technical and product knowledge of the users, and analyze the language skills of the users. Make safe assumptions. Ask yourself:
- Are you communicating to existing users, experienced users, or novice users?
- How are users consuming the content? Online? Printed? Other media?
- Does the documentation takes care of accessibility issues, such as color blindness?
- Are you adapting yourself to the type of audience?
- Do you engage with technical support to find out the pain points? How good is the content? What is working and not working for the user?
- Are you taping other internal resources, like the marketing team, to get feedback on the user documents?
- Are you engaging with the customer?
- Have you thought about creating personas: An artificial or fictitious person who represents the user, and then viewed the content through the persona’s eyes?
#3. Highlight Hazards
Watch out for things that need special attention of the user. Figure out the pain points and high risk areas, and ensure you help the user navigate them.
- Finding hidden hazards through scenarios.
- Use a ranking mechanism to differentiate types of severities. For example: Level 1 = Danger, Level 2 = Warning, Caution or Attention, Level 3 = Note, and Level 4 = Hints or Tips
- Make hazards visually clear by placing them at the right place.
- Break them out of body text
- Highlight them via icons, imperative sentences, or simple do/do not statements
- Explain the ramifications and workarounds
#4. Break it Out
7 years ago it was known that users spend 30 seconds on a page to look for information. And the trend over time has been a shortening of this length of time users spend on a site. What’s crucial for a Technical Writer is giving proper structure to the content so that it’s easier for the user to find the information.
- Keep the sentences short.
- Think visually and reduce the text. Use graphical illustrations if useful.
- Provide structure to documents, use headings, bullets, Include tables, steps, flowcharts for decision making, and branching options in a process.
- Think about the way people need information (text versus non-text).
#5. Don’t write blind
If you don’t understand something, don’t write about it. It’s your job to know the product and subject matter. Do not rely on second hand information. Explore the product, see it, use it, and touch it. Get to know it inside out. Ask open ended questions to get the right information from the SMEs (Subject Matter Experts).
#6. Be Consistent
When you are writing the same thing in three different places in the document, do not write it differently each time. Take care of technical terminology and pick one term. It’s also important for localization.
- Decide how to refer to the product.
- Consider interface elements and actions
- Don’t forgot styles, fonts, and layouts
- Use a style sheet.
#7. Signpost!
Use signposts to direct the user to the correct information at the appropriate place in the document. Provide proper references and cross-references wherever needed. Use layout and typography to indicate relationship of elements. As part of a documentation suite make all parts aware of each other.
#8. Don’t violate (legitimate) standards
- Do not use non-standard terminology.
- Recognize the difference between a legitimate (de jure) rule and a bad de facto custom. If certain things have been done because “that’s the way we’ve done them for years,” that doesn’t necessarily mean it’s correct. You may want to decide to change it.
- Develop knowledge about issues relating to regulatory and compliance requirements, such as ISO or EU directives, or any certifications or legal issues.
#9. Contemplate before you illustrate
Make a rational decision when you must have graphics (or video). Sometimes you may not need it at all or maybe you may need only a part of it.
- Use appropriate graphic types
- Use call-outs or annotations to focus attention.
- Use various image views like exploded view, isometric view, and so on.
- Place the graphic after the content.
#10. Cut the fluff
Flowery, vague language is fluff. Fluff is a serious issue with usability. Keep it simple and short (KISS). Don’t use:
- formal and pompous writing
- hidden strong verbs
- unnecessary passive voice
