November 3, 2022
Documentation, along with the actual Figma/Sketch/React components, forms the core of any design system. How can we make our documentation and component pages the best they can be? Here are a few tips I’ve picked up along the way.
There’s a lot of talk about designing atomically within design systems, but this principle can also help simplify and streamline your documentation itself. Focus each section of the page on a single facet of the component or pattern. Avoid mixing different types of guidance within the same paragraph. For example: when annotating the major building blocks of a component don’t also describe the string length requirements for textual elements; save that information for a dedicated Writing section that can more exhaustively cover voice and tone, content strategy, and similar text-focused guidance.
Organizing your documentation into a similar structure across every component page will help consumers quickly find the guidance they’re looking for. Not every page contains the same information, but many pages will have a least some amount of overlap in the type of content they include. Standard naming and formatting will help make this information more accessible as consumers become familiar with the system.
Here are some of the standard categories I find useful when documenting UI components:
Journalists often follow an inverted pyramid model when writing their articles, focusing on the most important and straightforward facts at the beginning of a piece and transitioning into less important background information towards the end of an article. Component pages should take a similar approach. Expect most consumers to read only a small portion of any page and organize your information accordingly.
The first chunk of the page quickly answers questions like: What is this component? What does it do? Is this the component I’m looking for? Then transitions into describing the core features of the component.
Use the rest of your content to flesh out the details of these features, their nuances, recommended configurations, etc.
Don’t be afraid to include a lot of information in your component pages, just structure it in such a way that obscure details don’t drown out the major points.
Imagine a perfectly organized, beautifully laid out, engagingly written component page, but every third paragraph contained out of date information. Accuracy is an essential element of design system documentation, a resource often referred to as the “single source of truth”. Make sure consumers can actually trust the information you’re sharing.
Seems obvious, but this can be harder to achieve in practice. Little tweaks get introduced, behavior is adjusted to make development easier, features get de-prioritized but remain in the design specs, etc.
A few tools to help combat the entropy:
Sometimes a picture really is worth a thousand words. Judicious mockups and diagrams can help clarify complex UI or concepts with just a glance. Brief gif or video animations can quickly communicate detailed interactions or motion designs. At the same time, images can lack the specificity possible with text. Not everyone reads the same thousand words when they look at the same picture. Don’t be afraid to include as much text as needed to fully explain the constraints of a component.
We know users scan and skim, rather than truly read. This behavior applies to design system documentation too. Often, your consumers will have at least partial familiarity with a given component, having used it before or seen it in other’s work. Writing atomically and organizing in standard structures does help optimize for this type of consumption, but you can go even further towards getting the most salient information before your consumer’s wandering eyes.
Do’s and Don’ts provide a stripped down way to reliably highlight the most important information for a reader to glean from a documentation page. While a design system guarantees a certain amount of consistency just by existing, you get the most bang for your buck when designers follow conventions and use their judgement to apply standard principles to diverse use cases. While you may explain these conventions more precisely or technically in the body of your documentation, the concrete examples provided by a set of do’s and don’ts help crystallize their meaning in more practical terms.
And there you are, six tips I’ve learned from my time working on design systems. If you have any thoughts on these or new tips of your own, do get in touch.
— Parker
Subscribe to posts by RSS.