Table of contents
In late 2023, Belka’s Sara Fazzini and Maria Sole Biondi interviewed designers, developers and managers at 27 companies in Europe and N-America to learn how they approach design systems. This article is the sixth in a series about what they learned. (Click here for more information.)
You may be familiar with this: after months of work, you release the end-game documentation for your design system components on Figma. It’s complete, well written, nicely formatted, and well illustrated: simply one of your greatest projects.
But flash forward a few months and nobody is reading it, nobody is using it, and the working product doesn’t align with it. People still ask questions on Slack that are answered by the documentation.
So why is nobody using your incredible documentation? Let’s dig deeper.
What ad how we document
"In the past, we made the mistake of looking for complete design system documentation. It was difficult to update, so in the end it became a bit of a graveyard. We are now rebuilding it in a simpler, more focused way, and things are getting better." - Craig Mann, Truelayer
Design system documentation is the set of guidelines and resources for using the design system correctly. This could look like style and component descriptions in Figma, on-canvas annotations, a codebase of naming structures, or articles and guides. You could host it in Figma or Storybook, or even on dedicated websites or tools (like Supernova or Zeroheight). All this documentation helps large teams keep their product interfaces consistent.
The problem arises when you are more excited about making the documentation nice and complete than making it a useful tool.
With a one-man-band guiding the documentation, it becomes detailed and perfected in a way that isn’t at all useful. Soon, no one will use it, it is expensive to update, and it’s inefficient for all.
Documentation, born as something to help everybody, becomes background noise.
RTFM (Read That Fucking Manual)!
Think of documentation like instruction manuals or video tutorials. It is supposed to help you breeze through a task by first explaining or showing you something. But let’s be honest, you often skip any read.me or “how to” when you simply want to do the thing and not read about the thing.
You only go through a read.me file if what you’re dealing with is:
- Precious or dangerous and you don’t want to make risky, expensive, or irreversible mistakes.
- Totally new and you genuinely have no clue how to start.
So, if you are familiar with Figma components, even just a bit, that can be enough to make you skip the documentation.
The moral: believing you can make any documentation and the team will automatically use it, well, that’s wishful thinking. Expect that people won’t read the fucking manual!
Should we break up with design system documentation?
After working hard on documentation for it to just be ignored by your team, you might be ready to walk away. But leaving this love-hate relationship is not the answer.
As teams and products grow, endless Slack threads are an inefficient way of sharing design decisions. So, documentation is essential. Still, a product team needs to take a thoughtful approach. They need to ensure documentation is serving them, not vice versa.
Our design system research at Belka uncovers why starting with “just enough documentation,” a sort of minimal viable product, is so important. The goal isn’t to complete it immediately, and you’ll find it’s hard to prioritize what needs to go in it anyway.
So, how can you start? How much documentation is enough documentation?
First, there are some aspects that are almost always in components documentation: anatomy, examples, and specific rules, plus components’ status and combination with other components. But there’s no one-size-fits-all way to document the design system: it depends on the size of your team and the product.
You’ll find that documentation evolves too - trying to lock it down in a “perfect” state only limits it. It needs to be flexible.
To achieve this usable, fluid and beautifully imperfect documentation, it’s all about teamwork.
How to get your team using documentation
Let’s break it down.
Listen to your team
Questions about using components and comments on the UI are the first real problems that documentation can solve. Questions become conversations, which lead to decisions. By tracking the questions people ask and how they’re resolved in conversations, you'll know what they are struggling with and what might be useful.
Include these topics in your documentation, step by step.
Let the documentation get messy
Hope for your perfect Figma page to become a dirty mess of notes and comments. Get people to discuss the component library and comment on the documentation itself.
We’re often tempted to keep the file clean, but cleanliness kills the instinct to add questions and comments. Cleanliness is a shortcut to the documentation graveyard.
Think about this: is the documentation reflecting the conversations you have with the team?
Keep it simple
Place documentation where people can easily see and reach it. Keep it concise and easy to update. Videos that show how to use components are nice, but too expensive to be updated.
Involve your team
People ignore documentation created in isolation, without their feedback. Getting your team involved isn’t just an obligation, but a way to find out what is really meaningful and should be documented — and what should not.
Without team input, it’ll contain a lot of things you think are useful, but are not in reality. Involving the team helps you avoid this mistake now and in the future.
Get the team together for regular check-ins to find out if the documentation is still useful. Collect issues, problems, and opportunities as you go.
Documentation is a long-term relationship
Good documentation covers interface decisions that come after many messy team discussions and questions: these conversations are where decisions are made, and where the documentation journey really starts.
The Figma file is only the tip of the iceberg, the last mile stretch.
Don’t forget to feed your team questions and create space for discussion: it’s one of the most powerful ways to make your documentation grow with your team.
∗ ∗ ∗
This article is part of a series of articles about design systems practices in the real world, based on interviews with design and developers at 27 tech companies in Europe and N-America, conducted in late 2023.
Belka would like to thank all the great people we talked to at the following companies for their help with this project: Balsamiq, Buddyfit, Coverzen, DaVinci Salute, Docebo, Docsity, Doctolib, Fatture in Cloud (TeamSystem Group), Fiscozen, Generali, Immobiliare.it, indigo.ai, isendu, Jet HR, Klarna, Musixmatch, NeN, Nibol, 1Password, Scalapay, Serenis, ShippyPro, Subito, Switcho, Telepass, Tot, and TrueLayer.
Read more about the project here, and for even more, subscribe to Belka’s newsletter.
∗ ∗ ∗
Want more insights from our independent research?
- How do you know if your design system is giving you a return on investment?
- How being too much of a control freak can harm your design system
- Why isn't anyone using your design system?
Want a safe pair of hands to help with your own design system?
Check Design System Audit, our service to make sure your design system brings you results.
