Documentation. Most people see it as a chore, like cleaning out email spam: an unnecessary irritation that detracts from “real” work. But writing notes in design systems is as important as the visuals themselves. And it’s not hard.
Think of documentation as writing commit notes in git. You know it’s important, but you can read the code to see what’s changed, right? That’s not always the case — and neither is glancing at visual patterns in a design system to tell what’s what. In this article we’ll cover ways to turn mundane documentation into useful notes that help your design systems in the long run.
The “so what?” factor
Redundant or similar patterns lead to inconsistencies and confusion, resulting in a slightly sloppy end product. If you’re concerned with pixel-perfect or responsive web designs, then you need more than precise Photoshop or Sketch files. You need to understand each pattern’s intention, its reason to exist. Every pattern in a design system should have a unique role.
Documentation reflects this. If you can’t write down why a pattern is in your design system, then do you need it at all? One way to find out is to list instances where your team has used it. A zebra-striped table, for example, might appear several times in a web app. Could another pattern have replaced it? Probably not since only tables display tabular data. Therefore the purpose of a table pattern’s alternate striping is to help people discern rows (or columns) at a glance.
Notice that “a table supports tabular data” isn’t a good purpose. That function is obvious. The table’s design solves a readability problem, as documenting its unique look explains.
What to write
Writing notes is more than jotting a pattern’s name and visual description. Three bits of information will make documentation as useful as the pattern itself.
What makes the thing you’re documenting unique? Each pattern needs its own purpose. For example, “Use this button to more attention than ‘cancel’” or “Use this panel when you need to make something look draggable.”
What are its parameters? How much content — text, images, media dimensions, etc — will help others decide if this pattern is right for them. Describe the most and least material it can contain, and how far it’s designed to stretch. If a calendar widget can only stretch across three columns before looking silly, for example, then you need to write that in its docs.
When was it made? Dating or versioning your patterns will help your team (and your future self) decide if the pattern is due for an upgrade, and which was built solidly enough to stand the test of time.
A documentation template
Still stuck for what to write? Try filling in these blanks: “I designed the (name) pattern to (goal). Use this pattern when (purpose). Intended parameters: (specs).” Some examples:
- “I designed the Primary Button pattern to make calls to action stand out from other buttons. Use this pattern when you want to encourage reluctant people to click. Intended parameters: One column wide, 30–40px tall.”
- “I designed the Intro Paragraph pattern to show readers where to start reading. Use this pattern when the top of your blog design looks cluttered. Intended parameters: three to five columns wide, 40–60 words long.”
- “I designed the Feedback Notice pattern to tell users the results of their actions. Use this pattern when you need to inform them that hitting ‘save’ worked, or when an error occurred. Intended parameters: 10–12 columns wide, 60px tall. Use brand ‘blood orange’ for warnings, brand ‘forest green’ for success.”
- “I defined the ‘Forest Green’ color as a way to stand apart from brand ‘sky blue’ for people with vision problems. Use this pattern when you need a cool color that contrasts well with the background. Intended parameters: #33691E.”
Write well. Compose two to three complete sentences per item, tops. Words are useless without context, so don’t settle for vague phrases. Thorough design doesn’t stop at the pixels. Content counts.
Consider SEO. The easier finding patterns is, the more likely people are to stick with a design system. To that end, remember that search engine optimization isn’t just for Google. It’s for any search tool — including the one in your design system, if it has one. And if it doesn’t, SEO means how well headings are to manually scan. Keywords are the key.
Review with teammates. Ask someone else’s opinion: does this make sense? What is it lacking? Like any user testing, getting an outside opinion will reveal dangerous assumptions in your thinking.
Stick to the topic. You don’t have to write a pattern’s life story to give people the gist. Most people referring to a design system just need one thing, and they may be in a hurry. Don’t wander onto tangents. Most kittens are fuzzy.
Building a stronger design system
Documentation may sound like a chore, but it’s a vital part of creating a design system. Spelling out each pattern’s purpose and best-use case will help your whole team understand not only the value of that pattern, but the value of your design system overall. Refer to these notes as you write yours.