How to improve your design system documentation

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.

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.