Documenting Documentation

Linda Dong
Jun 21, 2018 · 1 min read

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)

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store