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)

→ Read-o-Meter

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)