How to improve your design system documentation

Write more effective design system documentation with top tips from Dan Mall, Design Systems Leader & Coach.

3 min read

January 30, 2023

Learn design systems

Design system documentation is important for several reasons: It promotes collaboration, reduces design debt, and helps create a scalable and flexible design system. However, writing effective documentation that's easy to follow can be a challenge. To help you improve your documentation efforts, design systems Educator, Dan Mall, suggests changing your approach — don't document, chronicle.

With over a decade of experience developing design systems for world-renowned brands like United Airlines, ExxonMobil, Nike, and Eventbrite, Dan Mall is considered a product design pioneer whose expertise has been imparted at conferences, private client engagements, higher education, and more.

Watch Dan's top tip for improving your design system's documentation.

Don't document, chronicle.

Dan Mall: There are usually two big things that make design system documentation difficult. First, writing it is really hard. Secondly, even when you do write it, people don't follow it anyway. So what do you do instead? Don't document, chronicle.

Most people write documentation first before they do anything, which is kind of like a spec, and people don't like following specs because it's usually unfamiliar to their workflow. That's the key.

Instead of documenting what should be done, chronicle what has been done. This will make it much easier for people to follow your design system because you're giving them insight into something that already works.

"Instead of documenting what should be done, chronicle what has been done." Dan Mall

Dive deeper into design system documentation in Dribbble & Dan Mall's upcoming Scaling Design Systems course. Upgrade your design career in just 8 weeks with flexible learning, design systems mentorship, and hiring connections on Dribbble.

Learn design systems online with industry experts

Browse course
  • Design mentorship

  • Flexible learning

  • Hiring connections

You might also like

creativity design systems

Do design systems limit creativity?

January 24, 2023 3 min read
design tokens

Design Tokens 101

January 23, 2023 7 min read
front-end developer skills

Essential Front-End Developer Skills Needed in 2023

November 04, 2022 12 min read
design system example

12 Leading Design Systems You Can Learn From

November 18, 2022 12 min read