Design system teams frequently ask us how much they should document about their design system. People worry that too much documentation means a lot of work they don’t have time for, and people are less likely to read it. But too little documentation means people won’t find value in the documentation and refrain from using it. This article will discuss determining if you’re writing too much or too little. We’ll also mention best practices for documenting your design system, so you’re working smarter and not harder. Let’s jump in!

Determine if you’re writing too much or too little

The best way you can figure out if you’re writing too much or too little is to ask the people who should be reading your documentation. The emphasis is on “should be” because if they should be but aren’t, there’s probably a reason why. Additionally, ask the people who currently read the documentation and those that contribute to or maintain the design system. The people you ask should include a mix of roles – content writers, designers, developers, product managers, etc. We recommend doing short qualitative interviews with 6-8 people. Interviews allow you to ask follow-up questions and dive into deeper topics. Running a survey is another option, but it might not give you the qualitative feedback you need when determining if you’re writing too little or too much. If your design org has user researchers, we recommend teaming up with them to select a good set of questions to ask. Some questions that can help determine if there is too much or too little information include:

• What information are you looking for when you go to our documentation?
• How easily can you find the information you’re looking for
• What information is missing from the documentation?
• What information do you feel is unnecessary?
• What information in our documentation is helpful for you?
• How could our documentation help you be successful with your work?

Tips if you’re just starting to document

If you’re just starting to document your design system, you might feel overwhelmed that you have a big task ahead. We often see beautifully documented design systems and want to get there, too. While it does take some effort, it doesn’t have to happen overnight. Material 3 didn’t appear out of thin air; it evolved over the years since Material Design’s debut in June 2014. Here are some tips if you’re just starting:

1. Prioritize what to document

Your documentation doesn’t have to be complete before people can use it. Instead, take a phased approach and prioritize what you’ll document. Depending on your team’s availability to document, you might create phases based on sprints, months, or quarters. When prioritizing, consider what components or patterns your product(s) frequently use. Those might need documentation first; later on, you can move on to writing about principles and governance. If active changes happen to components or patterns, it might be worth prioritizing writing about them. For example, if your navigation design is changing, documenting the details will help with the transition and adoption of the new design. If you’re unsure how to prioritize your components, we have a great article to help you figure that out. Your documentation can follow this priority, too.

2. Start lightweight

Once you identified a priority, you can start documenting. Your documentation doesn’t need to be thorough. It’s more important that it’s accurate so people can build that trust in it. Start with bullet points rather than write huge paragraphs explaining states, usage guidelines, etc. Here’s an example of wordy documentation:

Breadcrumbs provide the user with a sense of location within the site. When using breadcrumbs, include the full path of the page. Sometimes, the breadcrumb will be long; in that case, the breadcrumb should truncate. We truncate breadcrumbs at the beginning of the path. Lastly, users can select an item in the breadcrumb path to navigate to that page.

Here’s an example of the same content but in a bullet point format:

Breadcrumbs provide the user with a sense of location within the site. Here’s how breadcrumbs should display:

• Include the full path of the page
• For long breadcrumbs, truncate the path at the beginning
• Items in the breadcrumb are selectable; selecting one will navigate to that page

3. Get feedback early on

No one wants to work so hard on documenting only to find out no one’s reading it. We recommend writing documentation for 1-2 components and 1-2 patterns. Before going any further, ask people who would be reading your documentation for feedback. They might shed some light on what’s missing or unimportant. Remember that what someone thinks is trivial might be necessary for someone else (e.g., a new employee). The design system team should make the final decision on what the documentation includes. After initial feedback, consider including opportunities for any-time feedback in your style guide with the page rating feature and feedback footer option.

Tips for working smarter and not harder

1. Focus on content, not a top grade in English class

The term “documentation” implies many paragraphs of text, but it doesn’t have to be. Actually, it shouldn’t be. People reading your documentation are busy and need information right away. If you think about it, our attention spans have become so short, which is why TikTok, Reels, or Stories are so popular to consume. Even today, a YouTube video over 5 minutes seems unbearable. Consider how this affects how willing people are to consume your documentation. With that in mind, here are some tips:

• Keep your documentation as concise as possible. Letting Go of the Words by Ginny Redish is an excellent resource. She includes examples of removing extra words and cutting out the fluff.
• Use bullet points whenever possible to keep things concise.
• Use an image or rule block to convey essential information whenever possible. This might be useful if you’re having trouble explaining something in words. Adobe’s Spectrum documentation does this well.

2. Create general guidelines for areas of focus

I’ve seen design system sites where each component has a section on accessibility. It’s great to see and essential to have, but typically for every component, the information will say something like, “There should be enough color contrast with this component.” That’s a standard guideline across the majority of components and patterns. Rather than write that for each component and pattern over and over, consider writing a page of general guidelines on accessibility. Add a caveat at the top saying that these guidelines apply to all components and patterns unless otherwise specified on that component or pattern’s page. Doing this helps with two things.

1. You don’t have to repeat yourself over and over. You also don’t have to update every page if something changes globally.
2. People who consume your documentation can quickly familiarize themselves with general guidelines rather than try to figure out what’s global and what’s not when reading individual pages. They’ll know when they see a section on accessibility on a component there’s something special to pay attention to.

You can write general guidelines for the following:

1. Accessibility - how your UI provides accessibility for its users
2. Localization - how your UI will adapt to different languages
3. Responsiveness - how your UI will adjust for different devices
4. Native vs. custom/product - when your UI should choose to use the native operating system’s component/pattern instead of a custom one that’s specific to your product
5. Voice, tone, and writing style - how to write copy for your components, including vibe, grammar, etc.

Typically, you can place these guidelines with the other foundations of your design system (e.g., color, typography, etc.).

3. Leverage synced pages

You can use the synced pages feature on the Enterprise plan with zeroheight. This allows you to pull specific pages from one styleguide and display them in another. The feature is great if you split your documentation into multiple styleguides for different products or devices but have core documentation (e.g., principles, brand colors) they should all share. Syncing pages to a styleguide will streamline the reader’s workflow because they can stay in one styleguide instead of jumping to different resources for information. The best benefit for synced pages is that maintainers only have to update the core page instead of going to each styleguide to make the same edits over and over.

4. Write only what’s necessary

Writing only what’s essential sounds obvious, but losing track of what’s needed is easy. When you document your design system, note how it currently works, not how it will work in the far future or how it’ll ideally work. Your design system documentation should reflect what people should use today or soon (e.g., three months from now). It’s tempting to include usage guidelines that you might find in another aspirational design system, but it's unnecessary if it’s never something your products would encounter. You might feel like getting ahead of documentation by adding things you’d like to include eventually, but if it’s not getting implemented, it’s best to hold off. When you add items too soon, they can feel irrelevant or confusing for people. In either case, people reading your documentation won’t feel like they’re getting value from the system (read: they won’t use it), and without adoption, your design system will fail regardless of how nice it is.

5. Check your writing for grammar and conciseness

Use a tool like Hemingway App, Grammarly, or even Microsoft Editor in Word to ensure you’re writing well. We highly recommend using a tool to vet your writing, especially if you and your team are short on time. Having teammates review your writing to vet the content is a good idea, but letting the tools check grammar and conciseness speeds up the process.

When is it OK to write less or more?

There’s no hard-and-fast rule regarding how much one should write for their documentation. Much of it will depend on your readers. If they’re a newer team, they might need more guidance, and that’s OK. If they’re a seasoned team, they might need less. At the end of the day, you want to make sure your design system documentation provides value to the people who use it. Here are some considerations on when it’s appropriate to write less or more:

• Experience of the team - if the team is more experienced or very involved in the design system, you can get away with writing less - for now. You should provide more details as new people join the team.
• Significant shifts in the design system - anytime there’s a significant change, it’s good to have documentation to help inform the team
• Documenting important technical details - sometimes, components might need coding in a specific way for accessibility. This might mean you must include more information or context to help the reader.
• Other elements like component uploads or rule blocks are helpful on their own - If you include them to illustrate guidelines, you might only need to explain things in writing partially. If you feel you’re repeating yourself, it might be an opportunity to cut back on the writing.

Learning more about documenting

We have several resources available to help you determine what to include in your documentation. If you want to get the team on the same page, consider trying our workshop on writing good documentation. Here is an article with some overall guidance on documenting components and an article that goes into more specifics. If you have more questions about documentation, feel free to contact us at community@zeroheight.com and on zheroes, our Slack community, which is free to join.