Back to Basics: The 10 Golden Rules of Technical Writing

Overview

• Speaker: Leah Guren
• Experience: 30 years in Technical Communication
• Focus: Fundamentals of Technical Writing, process, and methodology rather than tools or domains.

The 10 Golden Rules

1. Paper is Permanent

   • Responsibility for written content.
   • Importance of proofreading and structure.
   • Key considerations:
     • User judgment of product quality based on documentation.
     • Quality: Accuracy (errors, typos, etc.)
     • Usability: Clear, standalone, and non-ambiguous information.

2. Know Your Audience

   • Identify the user demographics and technical knowledge.
   • Ask questions:
     • Are users existing, experienced, or novice?
     • How is the content consumed?
     • Does it accommodate special needs?
   • Engage with tech support and create user personas to focus on the intended audience.

3. Highlight Hazards

   • Identify and clarify hazards for users.
   • Use a ranking mechanism for severity:
     1. Danger
     2. Warning/Caution
     3. Note
   • Make hazards visually distinct and provide explanations.

4. Break it Out

   • Users often spend only seconds on a page.
   • Structure content for ease of use:
     • Short sentences, visual aids, headings, and lists.

5. Don't Write Blind

   • Understand the product you write about.
   • Avoid reliance on second-hand information; engage with SMEs and ask open-ended questions.

6. Be Consistent

   • Consistency in terminology and styles is crucial.
   • Consider actions, interface elements, and layout.

7. Signpost!

   • Use signposts to guide users to the right information.
   • Indicate relationships between elements through layout and typography.

8. Don't Violate Standards

   • Avoid non-standard terminology and recognize legitimate rules.
   • Stay informed about compliance and regulatory issues.

9. Contemplate Before You Illustrate

   • Assess the need for graphics carefully.
   • Use appropriate graphic types and place them after relevant content.

10. Cut the Fluff

• Avoid vague language; keep writing clear and concise (KISS).
  • Identify common fluff elements to eliminate.

Conclusion

• The golden rules aim to provide a user-centric approach, aid editorial choices, and support decision-making in documentation.
• Leah Guren's engaging presentation style enriched the learning experience.