Writing more effective design system documentation
Practical tactics for writing helpful design guidelines
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.
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 questions 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.
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.
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:
- 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.
- 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.
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.
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.
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.
Remember, headlines serve a practical purpose too
For many documentation websites 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.
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:
- Writing is hard but maintaining what you’ve written is exponentially more difficult
- Putting content in is easy, taking it out is really hard
- 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.
- Documenting Components by Nathan Curtis
- Maintaining design systems by Brad Frost
- Expressive Design Systems by Yesenia Perez-Cruz
- Everyday Information Architecture by Lisa Maria Marquis
