Documenting Documentation

Quick tips on how to write design guidelines

👏 Be Concise

A mountain of text is intimidating and uninviting. Aim to:

  • Keep to less than 400 words
  • Use short sentences
  • Break up paragraphs longer than 3 sentences
  • Turn long sections into other articles when appropriate
  • Avoid repeating yourself
  • Avoid using passive voice
  • Avoid repeating yourself

👶🏻 Make it Accessible

Could a non-designer understand what you wrote?

  • Use simple words
  • Keep it conversational
  • Avoid acronyms (no one knows what they mean)
  • Break up articles into meaningful sections
  • Use images to explain concepts
  • Provide “Do’s and Don’ts” and concrete examples
  • Provide direct links to resources
  • Add a “Related Content” section at the bottom of your article

😃 Keep it Positive

Upset or passionate about a process? Had a bad day? Keep it in a journal!

  • Avoid bold, italics, and ALL CAPS. They look aggressive.
  • Reframe negative direction into positive direction (“Don’t use black” → “Use grey”)
  • Keep PSA’s friendly and understanding (“Please contact us and we’ll try our best”)
  • Use a tasteful amount of exclamation points

Fantastic Resources

Hemingway App

Flags how complex and readable your text is (aim for a Grade 6)


Estimates how long your text takes to read (aim for less than 3 min)

Mr. Rogers’s Rules For Talking to Children

Great 9-step writing guide (for adults too)