📝

Essential Guidelines for Technical Writing

May 25, 2025

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.