Documentation is the bane of existence for many design system professionals, a necessary evil that produces groans and eye rolls at the mere mention of its name.

Much of that stems from our preconceived notions about what documentation is supposed to be. If you look at some of the popular, public reference websites for design systems like Material Design or Carbon, most documentation is comprehensive technical text and usage instruction.

But this kind of documentation is antithetical to true Agile software development practices. The second principle of The Agile Manifesto is “working software over comprehensive documentation.” Working software is the real source of truth, not the documentation.

While many agree with this in principle, putting it into practice is often elusive. One of the biggest shifts I’ve found is quite literally changing our minds about what documentation is, and, therefore, needs to look like.

I love the way that Agile coach Jeff Patton talks about documentation in his excellent book User Story Mapping:

If I show you one of my vacation photos, you might see my kids on a beach and politely say, “That’s cute.” But when I look at my vacation photo, I remember a particular beach in Hawaii that we had to drive more than an hour on a deeply rutted four-wheel drive trail, and then hike another half hour over lava fields to get to. I remember my kids whining, saying, “Nothing could possibly be worth this,” and me wondering the same thing. But it was. We enjoyed a blissful day on an incredible beach where very few people were, which is why we took the trouble to get there. The turtles came up on the shore to bask on the sand, which was the icing on the cake of this fabulous day.

​Of course, if you look at the picture, you won’t know all that because you weren’t there. I remember all that because I was.

​For better or worse, this is the way documents actually work.

Yes! At their largest scale, design systems are more than just tools, templates, and artifacts. I love how design system consultant Brad Frost puts it:

A design system is the official story of how an organization designs and builds digital interfaces.

Patton’s vacation photo anecdote substantiates the old mantra that a picture is worth a thousand words. But even if you had a thousand words, you still wouldn’t be able to tell his story; you could only describe the photo at a surface level. And that’s not enough to convey what really happened.

As he puts it elsewhere in the book:

Shared documents aren’t shared understanding.

That’s the biggest problem with most design system documentation: it prioritizes the document over the understanding.

What to do about this dilemma? Patton has some advice:

Stop trying to write the perfect document.

​Go ahead and write something, anything. Then use productive conversations with words and pictures to build shared understanding.

​Stories in Agile development get their name from how they should be used, not what you write down. If you’re using stories and development and you’re not talking together using words and pictures, you’re doing it wrong.

Too much of design system documentation is intended to eliminate conversation, all under the noble pretense of “working at scale.” But we need more conversation, not less.

One final admonition from Patton:

What’s most important isn’t what’s written down. It’s what we remember when we read it.