How to document your design system components

Documentation is the cornerstone of a design system; without it, your design system will just be a component library.

It isn’t easy to write good documentation, and it is even more challenging to make your documentation attractive because so much information can go into a component page.

So what are the best ways to write good documentation and ensure people read it? To help you get started, here are some tips and best practices.

How to structure your design system documentation

It is possible to write documentation in many ways, but to ensure your documentation will be helpful to your users, you should consistently follow a few best practices.

The right questions to ask

When structuring your documentation, you should ask three main questions: why, how, and when.

• Why should you use it? Consider whether it is used to indicate something, respond to something, or respond to a particular event. Find out why you are using it.
• How should you use it? Ask yourself whether it should be used specifically, with another element, etc. Find out how you should use it.
• When should you use it? Consider if it should be used for a particular need, for a specific action, after an event, etc. Find out the right moment when you should use it.

Categorize your documentation

Documentation should be user-friendly, but it should only require users to read some of it to find the information they need. Divide your documentation into sections to make it easier for your users to find the information. Documentation can be organized into the following categories:

• Editorial: it’s all about the copy guidelines you apply to your component. Punctuation, tone and voice, maximum word length, etc. Are you supposed to capitalize your titles? What’s the right way to speak to your audience in a pop-up? What’s the maximum number of words that can be in your buttons?
• UI design: here are the guidelines for your components’ visual elements. Colors, layout, iconography, etc. Are there any specific rules about using colors on tags or icons for the primary button or where the back-to-top button should always be placed?
• UX design: here, you can specify the interaction rules for your component. States, conditions, action triggering, etc. How does this card behave when hovered? Does the error message appear before or after submission, or what happens when the confirm button is clicked?

You can use these categories to organize and structure your documents since they usually cover most of your needs. You can undoubtedly add more categories if they make sense for your content and your system. It could be about accessibility, technical guidelines, how to use the component in Figma, etc.

Dos & don’ts

Despite clear and rich documentation, you must remind your users what they may and may not do with your system. While you may be repetitive with the rules you have written, it’s also very likely that your users only read some of them. The do & don’t section makes sense as it’s an easy-to-read and visual section that ensures people quickly understand the essential rules.

Visuals

Documentation can be overlooked when it’s just a “wall of text.” Using visuals in your documentation can help you capture your audience’s attention. Images speak louder than words. Components and patterns illustrated in a use case will be much more effective in helping users understand it at a glance and get their attention so they can read the whole thing.

A good visual example from Teamleader’s design system

Using a workshop for your documentation

The process of structuring documentation is one thing, but writing it can take work. That’s why using a workshop to write documentation could be a good idea for you, your team, and your design system. To help you get started, we’ve made a Figjam template and an article to help you conduct a documentation workshop.

Better engagement

As difficult as it is to write documentation, ensuring people will correctly read and apply the information is even more challenging. A documentation workshop is an exciting way to engage your users with your design system while ensuring they understand and apply its documentation correctly. Furthermore, since they will be involved in the process, they will be more invested in it and will therefore be your best advocates for spreading your design system. As such, a workshop is an excellent way to engage and reach more people.

Better vision and overview

Building your design system on your own is the best way to ensure nobody will use it. That’s why conducting a workshop with multiple people is an excellent way to enhance engagement. The other reason to invite people to contribute to your design system documentation is that you will have a much better understanding and a more precise vision of how the components and patterns are used. A diverse range of views from designers, developers, product managers, marketing, and more ensures that your documentation will meet the needs of all users of your design system.

Better performance

Although it might seem expensive to involve so many people in documenting, you need to look at it in the long run. Investing in design systems means documenting them appropriately. Spending time documenting components will ensure people can utilize them more effectively on projects. The quality of the design, the integration of development, and the collaboration between the teams will be improved by understanding how the product, the brand, and the components work together. Investing time in these workshops leads to better documentation and collaboration among your team members.

Closing thoughts

A well-structured design system is essential for a robust and mature system. Hiring a dedicated content writer to help you write the proper guidelines for your components and patterns may even be a good idea.

Last but not least, if documentation is the heart of a design system, then the people who work with it are the ones who make it beat. Because of that, your documentation requirements can help you connect your teams and make your design system more engaging for everyone. To help you structure your documentation, read our article about conducting a documentation workshop. There is even a Figjam file you can reuse so you can get started quickly and efficiently!

We’d be curious what you think is the best way to document your design system and how this workshop is helpful (or not) for you and your team. Don’t hesitate to give us your feedback on zheroes, our zeroheight Slack community, and share your thoughts on this topic!