6 tips for writing effective design system documentation

Practical tactics for writing helpful design guidelines

Ross Moody
Jan 6 · 6 min read
Image for post
Image for post

I wrote this article to document what I’m learning professionally while working on the new Garden Design System site in 2020. Like this article? Check out Defining Design System Principles.

Writing design system documentation

Creating effective documentation is a really important part of a design system. The key word there is effective. My experience with design system documentation is that there is rarely a shortage of information. Helping people understand how to use the system by presenting it in an organized and succinct fashion is the hard part.

Image for post
Image for post

To make matters worse, design system documentation is a moving target. Standards and guidelines evolve over time with the products they serve. You don’t write it once and move on. You write it once and maintain it forever.

I’m a designer by trade so to keep from getting overwhelmed with all these words flying around, I started to record practical tactics to use for auditing my own writing habits.

1. Partner with a writer

This is a rather odd tip to lead with for improving your writing but the hard truth is if you aren’t a UX writer or a content strategist, reading this blog post isn’t going to make you one. The tips below will help set a better foundation for communicating a cohesive vision, but most good practices I’ve learned (including these principles) are from writer feedback.

It’s going to take the best parts of a lot of roles to craft effective design system documentation. That’s the point. It’s a combination of best practices from all the different disciplines in one place.

2. Fight to shorten everything

Time is money and documentation isn’t exactly riveting. Most readers are here to answer their question and leave — not read leisurely.

The single most important question I ask myself while editing is “Can I say the same thing with fewer words?

Lead with examples

If you find yourself trying to explain context, scenarios or applications — ask yourself “Would an example work better here?”. It gives readers relatable UI applications and it’s much easier to digest.

Break up large blocks of text into a list

Large blocks of paragraph copy can feel intimidating. Increase the scannability of dense paragraphs by formatting copy into lists.

Image for post
Image for post

Prompt action

Most readers are here looking for direction. Leading sentences with action verbs in an active voice is a good way to give clear direction and shorten copy at the same time.

Image for post
Image for post
Ditch permissive language like “you can…” or “you should…”

3. Be mindful of absolutes

Except in rare cases, avoid phrasing rules or guidelines with absolute adverbs.

Saying a reader should “never” or “always” do something is a very difficult bar to set with absolute certainty.

The probability that there will be an exception to any given rule is high and this creates two problems:

  1. It creates a culture of rigid rulebook design thinking. The focus gets placed on following the rules instead of using educated judgement to craft a great experience.
  2. It trains readers to find loopholes. Every time an exception to an absolute rule is found it hurts the integrity of the documentation. Worse, it can make truly non-negotiable rules seem optional.
Image for post
Image for post

Solicit a reader’s judgement

Design systems serve to be assistive and empowering — not authoritarian. Providing direction with rationale can be more approachable than rigid rules without context. Consider prefacing direction with “It’s best to…”, “Avoid…” or “Consider…”. It accomplishes the same goal and doesn’t feel as domineering.

Note: Too much rationale can make the documentation seem lengthy and daunting to read. Too little, and designers will feel like they are following an instruction manual. Finding a balance is difficult.

4. Favor the positive over negative

Lead with positive communication instead of focusing on bad practices. Repeatedly focusing on negative patterns to avoid can put a reader on the defensive.

Note: There is a ton of valid and necessary reasons to advise not doing something. The primary point of this tip is to be mindful of finding a balance so the tone doesn’t feel accusatory or make the system feel oppressive.

Image for post
Image for post

Provide favorable alternatives

When you use negative examples to illustrate a point, provide a favorable alternative. This helps the direction feel constructive instead of like a dead end.

Image for post
Image for post

5. Write headlines with purpose

Think of a headline as a singular point you are trying to make. Most readers are scanning headlines for key words on a problem they want to solve. Typically the more explicit you can be, the better.

Image for post
Image for post

Remember, headlines serve a practical purpose too

For many documentation websites (including Garden) headlines play a practical role as well as a hierarchical one. Headlines get used in the URL so readers can link others to a specific section of any given page.

Image for post
Image for post

This means all headlines have an opportunity to give readers an idea of what they stand to learn from navigating to the URL. The more explicit you can be, the more shareable and accessible the entire site becomes. This is a win for page hierarchy, SEO and shareability simply by taking extra care in your headline verbiage.

6. Write to empower, not restrain

This last rule is more of a personal design system ethos than practical rule but it guides a lot of my approach to writing.

To a design system with a hammer, everything looks like a nail.

That is to say, I always try to be mindful the documentation isn’t becoming too prescriptive. Design systems are about empowering others with tools and information to improve upon what has already been built — not police against it.

To be clear, deviations from established standards need to have merit. A lot of shared consideration, effort and learned usability is taken into account when writing design standards. Predictability is usability. Intuition is muscle memory. Those things must be respected.

That said, a design system will not, and should not, contain an answer for every situation. At the end of the day a typical design system team has bandwidth to work on new documentation or police the old, but likely not both.

Consider maintenance cost

I’ve been to a lot of design systems conferences. There are usually a few foreboding themes the speakers touch on that I’ve grown to take to heart while editing:

  1. Writing is hard but maintaining what you’ve written is exponentially more difficult
  2. Putting content in is easy, taking it out is really hard
  3. Even the most successful design systems have limits

Final notes

There is no shortage of things to consider when writing effective documentation. If you want to learn more, here are a few of my favorite resources on the subject.

  1. Documenting Components by Nathan Curtis
  2. Maintaining design systems by Brad Frost
  3. Expressive Design Systems by Yesenia Perez-Cruz
  4. Everyday Information Architecture by Lisa Maria Marquis

Don’t forget to check out design.zendesk.com for more thought leadership, design process, and other creative musings.

Zendesk Creative

We're a blend of art, copy, video, and product design.

Ross Moody

Written by

Product designer by trade, front-end engineer at heart. Working on the Garden Design System @zendesk . Previously @brave and 55 Hi’s.

Zendesk Creative

We're a blend of art, copy, video, and product design. We come from different backgrounds, but we share one passion as the Creative team—making compelling work for Zendesk.

Ross Moody

Written by

Product designer by trade, front-end engineer at heart. Working on the Garden Design System @zendesk . Previously @brave and 55 Hi’s.

Zendesk Creative

We're a blend of art, copy, video, and product design. We come from different backgrounds, but we share one passion as the Creative team—making compelling work for Zendesk.

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