Creating Effective Documentation

[kychua]

Synopsis

How to craft documentation that is

• useful
• engaging

so users actually read what is written.

View slides
Download slides (with correct animations/transitions)

---

PUMA

• Audience: fellow CS3281/2

• Objective: Encourage creating more effective documentation

• Topic: How to create effective documentation

• PUNCH: Annoying to keep answering the same questions -> write better docs to reduce such questions? (e.g. Mozilla docs)

• WIIFY: Learn how to create more effective docs so you spend less time answering repeated questions (also, learn techniques relevant to other areas like writing online articles, teaching)

• Promise:

  • How to craft documentation that makes it easy for users to find what they need
  • How to write documentation that is engaging to read

• Content

  • Creating docs where users can find what they need
    • Multiple paths to the same info
    • Docs that can be skimmed (online reading): short paras with key point first, meaningful headers
      -> so users can find what they need
  • Writing docs that are engaging
    • Make users feel they're awesome: empowerment & motivation
      -> so users actually read what they need to

• Key points

  • Write docs that provide multiple paths to information and are easy to skim so users can find what they need
  • Write docs that make users feel they're awesome so users are motivated to read them
  • so you spend less time answering repeated questions

• Call to action: Write more effective docs

• Do: create effective documentation

• Believe: it is worth the effort

• Know: how to craft effective documentation, why it's important