Design System Documentation is a Moving Target — Panel Recap

In a recent panel discussion, we invited industry experts Romina Kavcic, a leading independent design strategist, Alberto Calvo, senior manager of design infrastructure at Maze, and Luke Finch, former NewsKit product designer, to share their experiences and insights on various aspects of design system documentation, including the process, challenges, and strategies for success. Here are the main takeaways from the discussion.

Creating the right documentation process for you

Different teams follow different documentation processes, ranging from editorial-like flows to more collaborative approaches. Involving all relevant stakeholders in the documentation process ensures that documentation is comprehensive and accurate.

“It comes from the designer to kickstart the documentation, but we are very involved in some of the milestones in the process." - Alberto

Some teams prefer to maintain unified documentation for both design and technical aspects, while others may have separate documentation for each area. They all agree that documentation is collaborative and needs certain practices to help make it work effectively.

Collaborative documentation is all about the people

Documentation that's created by everyone is better utilized by everyone. Here are some of the ways you take a collaborative approach to your documentation:

• Each person should be enabled to contribute their expertise to the documentation.
• Regular checkups and milestones can ensure the quality and consistency of the documentation. Alberto shares, “We agreed to commit to doing these regular checkups every 30, 60, and 90% of the projects.”
• For Romina, a centralized approach to documentation was more efficient and better suited to the team's culture and individual strengths.
• Using tasks or tickets to track documentation progress can help keep everyone on the same page and ensure timely completion.

Challenges in Design System Documentation

Many design system teams face some key challenges when it comes to their design system documentation. The panelists shared some of the challenges they faced and how they solved them.

Understanding user needs

One of the biggest challenges the panelists agree that design systems face is understanding users’ needs. This could be down to a lack of communication in the process or, in Luke's experience, language barriers being an issue. There are different ways you can go about overcoming this challenge:

• Romina recommends creating personalized educational content. It's important to utilize the different roles at your disposal, a designer can add extra context to the designs, and a developer can do the same with the code.
• For Luke, the key to overcoming this challenge is to be able to explain to different users in very simple terms why this could be useful and how to use it.
• Taking the time out for 1-on-1 sessions with different users can go a long way to understanding their needs.

Maintaining the documentation

Maintenance is a big chunk of developing any product similar to a design system. Making sure everything is up-to-date and easy to use is critical in documentation because it will reflect in the final product. Here's how our panelists faced this issue:

• Part of Luke's priorities is to make sure the documentation is easy to edit and easy for people to contribute to. Getting people involved as early as possible in the process is equally important to help shape it.
• Alberto shared, “Meeting people where they are(is key). We have dedicated jam sessions and office hours weekly. We also have design systems meets every month to communicate and discuss changes with the team, gather ideas, and see what's working and what isn't.
• Romina also encourages catering to remote team members with recorded videos or sessions highlighting updates and any new details.
• The panelists also agreed that utilizing tools like Supernova or ChatGPT can help you maintain your documentation more easily and faster.

Structuring your documentation

No two design systems are the same. They all serve different products, cater to different teams, and are structured very differently. How do you know how to structure your design system documentation? Our panelists offered some clues:

• Alberto's approach is similar in that a lot of groundwork needs to be done early to make sure the documentation on top of it scales smoothly. “What we did was start to systematize our documentation, the blocks, the structure, and how we use certain things.”
• Your documentation caters to your team, not the other way around. It's critical that the structure and process aren't set in stone but constantly evolve with every update according to the feedback you should get from users.
• Romina and Luke stress that making sure everything is connected won't fall on the contributing users. It's important for those managing the documentation to provide the added context and connect the components to make everything cohesive.

Prioritizing updates and communicating changes

All teams deal with finite resources. And it's important to be able to prioritize what parts of the documentation can be updated and to communicate these updates effectively. Here are some of the tips from the panelists:

• Prioritize updates based on urgency, importance, value, and connection to business objectives.
• Encourage feedback from design system users to understand their needs and address any gaps in the documentation.
• Use dedicated channels and regular meetings to communicate updates and changes to the design system.
• Treat documentation as a living document that can be updated and improved over time.

Measuring your documentation's success

To help you gauge how well your design system is doing and take it to the next step, tracking and measuring your documentation's performance. The panelists discussed how they measure the success or usefulness of their design system documentation, both qualitatively and quantitatively.

Qualitative measurements

The panelists recommended a few ways you could track qualitative measurements that can be applied to any design system regardless of scale or maturity.

• Connecting with team members and conducting one-on-one interviews to gauge the effectiveness of the documentation.
• Luke shared that he finds it very useful to conduct user research as if it were an external product. Scheduling calls and regular checkups with pseudo-random people to get as accurate of an assessment as possible.
• Understanding the needs of design system users and addressing any gaps in the documentation can help prioritize updates more effectively.

“Rotating to different departments and you spend some more time with them, even if it'sonline, and you see how they use the documentation, what they lack.” - Romina

Quantitative measurements

While the panelists focused more on qualitative measurements, they acknowledged that quantitative measurements can also be helpful in certain situations.

• Tracking the number of support calls and requests related to the design system can help identify areas where the documentation may need improvement.
• Using internal surveys to gather feedback from team members.
• Romina also recommends other metrics, like NPS, to measure user satisfaction.

By addressing the challenges, implementing effective strategies, and leveraging modern tools, teams can create comprehensive and accessible documentation that meets the needs of their users and stakeholders.

We hope you've found these insights helpful, and we highly encourage you to watch the whole panel in case you've missed it. There are a lot more details that the panelists go into, and you can also find their details in case you want to get in touch. If you have any questions or want to learn more, share them with us on Twitter or Discord.

‍