Documentation driven design

While at Converge ‘24 conference, Designs Systems WTF recorded a live episode of their podcast about AI.

Michelle and Luke discussed their changing views on AI creating documentation for Design System components.

During the recording, Luke mentioned that Scott Riley had changed their mind, or at least given them a crisis of confidence about using AI for this.

From memory, this was largely in recognition that the actual process of writing the documentation is in itself a useful act and a vital step in the process.

This rang true with me, the last component that made its way into the design system I work on used the documentation process to define the scope of the component, before we made it.

Lightbulb moment

I’ve worked with a lot of developers and test engineers over the years, my brain went ping, this is not a million miles away from the idea of Test Driven Development (TDD).

BrowserStack summarise TDD as “a software development practice that focuses on creating unit test cases before developing the actual code”.

This process has a lot of benefits, one of which being that the process of writing the tests actually helps define in more rigid terms what the code is supposed to do and helps highlight any gaps in the design early on.

The process has a secondary benefit, you don’t have all your tests to write at the end – a stage which is often missed by tight deadlines, sometimes even ignored.

What’s that got to do with Design System docs Dave?

The crossover with documentation in design systems now seems quite obvious.

You are likely already following a design approach that focuses on specs, scope and draft APIs before you put cursor to artboard.

Why not write the actual guidance before you start designing visually?

We could call this Documentation Driven Design (DDD).

Writing your documentation first will help:

• Define the scope and intent of the thing you want to make
• Expose multiple use cases and contexts you may not have considered otherwise
• Work with all disciplines within the team on something before anyone starts making anything

I believe the benefits of this approach will mean:

• Design and Development build to the long form guidance – meaning less chance for misalignment
• The team is forced into the context of how they will explain the decisions they’re making to the consumers of the system
• The guidance can be published or researched with before a design or coded component even exists. This gets valuable information out there sooner

If we go back to the original topic of the use of AI in Design Systems perhaps DDD would actually be the ultimate prompt for generating useable designs that actually met your requirements.

While I’ve been encouraging this kind of process without really realising it, next time we create something new I might try formalising Documentation Driven Design.

How about you?