The people who use your design system documentation
Michelle Chin
Common thread
Regardless of role, there is a common need for design system documentation. It often provides a single source of truth of information. This information makes people feel confident designing, coding, writing and articulating ideas and decisions. (Learn more about instilling confidence with an article Dan wrote.). It’s also a great onboarding tool for everyone, where they can get a foundational understanding of what exists, why, and how to use or contribute to the work.
Beyond designers and developers, many other roles use design system documentation. This guide provides a high-level overview of who uses documentation, how they might use it, and how you can ensure you’re providing value for them. Your organization’s roles and usage might differ. We encourage you to use this as a benchmark and talk to your teammates to ensure you meet their needs.
Designers and developers
Designers and developers are the primary users of design system documentation. Even though they are in different roles, they might visit the site to:
- Understand usage guidelines – how and when to use a component or pattern, when not to, and expected behaviors.
- Explore options for using alternative components or patterns.
- Identify coded components to share with other designers or developers.
- Find examples of products that use the component or pattern.
- Download libraries, visual assets, and files.
- Understand the broader foundations around design, editorial, accessibility, and localization approaches – especially if they’re onboarding to the team.
- Identify if there might be differences between design and code libraries.
- Showcase the site as a recruitment tool (if the site is public).
To help designers and developers find what they’re looking for:
- Provide links to similar or related components on pages.
- Document how a component or pattern is accessible, localization friendly, etc.
- Include examples of where people can see the component “in the wild.”
- Maintain a changelog for quick reference.
Content strategists, UX writers
Content people can be both consumers and contributors to design system documentation sites. As consumers, they might reference components and patterns usage so that they can write content accordingly. They might review the voice and tone guidance to ensure their copywriting aligns with it. A design system documentation site is also a great onboarding tool for them.
In many teams, content writers provide the copywriting for the documentation site. Additionally, they might contribute content patterns to your design system components or patterns.
To support content and UX writers:
- Provide a space for content patterns (This helps designers, too!)
- Include voice and tone as part of your design system foundation
- Invite content and UX writers to your documentation workshop so you can create the guidelines together
Product Managers
Product managers will reference the documentation to ensure alignment between the product and the design system. They also want to keep up with changes in the design system to see how it’ll affect current products or features and upcoming releases. From there, they can plan for changes and updates and set expectations with customers.
To aid product managers in their work:
- Maintain a changelog of updates for easy review
- Provide announcements (e.g., newsletter, slack messages) for design system updates
Use status tags to help provide a context of a component/page’s status.
Marketing and Brand Teams
Depending on how your organization is structured, your marketing and brand teams might be separate from the product design team. They might also have a different design system site. If that’s the case, they might be checking your design system documentation site to:
- See if there are product-specific components or patterns they can leverage
- Identify changes that might need to be made based on broader brand decisions
To help marketing and brand find what they’re looking for:
- Maintain a changelog for easy review.
- Involve them in workshops that involve brand decisions
- Set up recurring (e.g., monthly, quarterly) sharing sessions to show how the design system is evolving and to ensure brand alignment.
- Provide an open line of communication with those teams to discuss company-wide ad hoc updates.
User researchers
User researchers might review the design system documentation to understand how teams use components and patterns in a feature. This can help them:
- Prepare for usability testing.
- Make recommendations for updating components/patterns from their findings.
- See what components/patterns could benefit from usability testing.
We strongly recommend that you conduct usability testing for your components and patterns. Ideally, teams test components and patterns as part of a broader usability study. Sometimes testing components in isolation provides unrealistic results.
To assist user researchers:
- Maintain a changelog for easy review or indicate a component’s status – so researchers can see if they can fit in testing with other studies
- List when components were tested and include links to research readouts. (Providing this context helps everyone feel confident!)
Additional internal viewers and the public
Even if your documentation site isn’t accessible to the general public, you could have other employees view it. They just might be browsing, or they might be looking for information to leverage.
To help other viewers, we recommend you:
- Provide a contact page for feedback and to make your design system more personable
- Have a clear information architecture to make the site easy to navigate
- Write guidelines in clear, concise language and avoid technical jargon so that anyone can understand the details
- (If you have multiple design systems,) be clear about what your design system covers. You want to ensure employees don’t use the wrong documentation site for their information.
- (If possible), provide a roadmap or backlog to share what’s in progress on
- Provide the right level of privacy to any pages that the public shouldn’t access. You can do this through password protection or SSO authentication.
Who else might use your design system documentation?
While we covered the typical roles, some additional people may use your design system documentation site. Check-in with other teams to see if they might use your site, how often, and why. Also, consider connecting your design system site to analytic tools to get a sense of your users. You might be surprised by what you learn. Each organization is different, so we recommend talking to your users to ensure you meet their needs.