A few years ago, an article I wrote about keeping subscribers engaged in your design system really took off. I presented this talk at numerous conferences, which introduced me to hundreds of wonderful people who work on design systems every day. No matter how many design system teams I spoke with, there seemed to be a shared struggle around getting subscribers to use the tooling developed to make their lives simpler.
A key factor in incorporating new technology is the instructions. At Sparkbox, we believe a documentation site can be make-or-break for getting subscribers to use a design system.
What Is a Docs Site?
A documentation site, affectionately known as a “docs site” or “docsite,” is the single source of truth for a design system. A docs site is to your design system as Sass.lang is to SCSS. Developers know well the specific pain of finding a new npm package that promises to solve their problems only to discover the documentation is lacking. Documentation keeps users from searching through endless Stack Overflow threads trying to find someone who has the same problem they have.
A docs site provides design system usage guidelines for developers, but also for designers, subscribers, and other stakeholders too. Atlassian, Audi, Shopify, and many others make their documentation sites available to the public. One of my personal favorites is the IBM Carbon Design System; it’s truly a best-in-class example.
Why Do I Need One?
As I mentioned, getting subscribers to use the thing they built is one of the most common problems facing a design system team. A docs site is one way to make your design system easy to use. If a design system is user-friendly, subscribers are more likely to use it.
Design system teams are often small. A good documentation website often helps users solve their problems without direct intervention from a design system team. Too much integration support can take up valuable time that could be used to improve the design system. A docs site can be a hub of relevant links and other resources a design system subscriber needs to get their work done. If your design system is versioned, a docs site landing page is an excellent way to clearly communicate how and why subscribers can and should update to the most recent release.
A docs site can also house definitive guidelines that make decisions easy for folks building web pages. Clear content and branding guidelines mean developers spend less time asking questions of designers. Those questions are answered in a consistent way because the answers come from a page, not a person. I don’t have to guess what color an error message should be if we have a design token for that listed on the docs site.
Docs sites can also include performance budget metrics or accessibility guidelines, which provide evidence for technical decisions made in subscriber applications. I regularly link to the docs site when I do code reviews. A docs site can also include ways for subscribers to contribute to the system via feature requests or by adding directly to the source.
Creating a single source of truth for your design system reduces communication barriers, saves time for your entire team, and creates a more cohesive user product.
How Do I Build One?
One well-funded, fully-dedicated design system team I worked with had a completely custom documentation site. This site was a subscriber of the design system package and had numerous features such as a version switcher, integrated release notes, extensive written guidelines, copyable code examples, links to downloadable design files, and more. The design was custom, branded, and usability tested with subscriber groups. This level of effort in a docs site is the crème de la crème; it was the kind of site you could only hope to create with time and a team that really loved the work they were doing.
Your docs site does not need to be that elaborate to be successful. Often, design system teams work without a budget. You may only have a handful of minutes in between client project deadlines to build your design system. Your team may still be in the proof of concept phase, trying to earn executive support. But even in a grassroots system, you should have some sort of documentation resource.
I’ve built documentation sites for mobile apps that consist of example code blocks pasted into a Jekyll template next to screenshots of how they are meant to look in the app. I’ve built an infinite number of Storybook-based React systems that contain component-specific README.md files for any documentation we need. My current work has begun incorporating Zeroheight, a tool gaining popularity among design system teams. Zeroheight consumes both our Storybook and our Figma instance to generate a single source of truth convenient to designers, developers, subscribers, and stakeholders, without the added work of creating something custom.
Many of our smaller engagements at Sparkbox benefit from something more akin to a pattern library. Often, we still use a version of Cloud Four’s Drizzle, where documentation lives alongside the code but can be deployed as its own page. We build this solution for clients so often that we’ve developed an open-source template repository to get the ball rolling (find it on Github under sparkbox/design-system-starter).
How you build your docs site doesn’t matter; what matters is that you find a solution that is sustainable and useful for your team.
Conclusion
When it comes down to it, no matter who your audience is, a docs site is a key factor in the success of a design system. If your team doesn’t have this yet, a good place to start is getting familiar with what other people are doing.
Or you could always give Sparkbox a call. We’d love to help out.
Looking for more on design systems?
Sparkbox is dedicated to sharing our experiences and discoveries about design systems. Sign up to get updates on design system content including our annual Design Systems Survey!
