Quick Summary:
Words alone aren’t enough to safeguard best practices in the world of web design and development. Web design documentation must be like its medium — interactive and constantly evolving.
As an occasionally competent software developer, I love good documentation. It explains not only how things work but why they work the way they do. At its best, documentation is much more than a guide. It is a statement of principles and best practices, giving people the information they need to not just understand but believe.
As soft skills go in tech land, maintaining documentation is right up there. Smashing has previously explored design documents in a proposal context, but what happens once you’ve arrived at the answer and need to implement?
How do you present the information in ways that are useful to those who need to crack on and build stuff?
Documentation often has a technical bent to it, but this article is about how it can be applied to digital design — web design in particular. The idea is to get the best of both worlds to make design documentation that is both beautiful and useful — a guide and manifesto all at once.
An Ode To Documentation
Before getting into the minutia of living, breathing digital design documentation, it’s worth taking a moment to revisit what documentation is, what it’s for, and why it’s so valuable.
The documentation describes how a product, system, or service works, what it’s for, why it’s been built the way it has, and how you can work on it without losing your already threadbare connection with your own sanity.
We won’t get into the nitty-gritty of code documentation. There are plenty of Smashing articles to scratch that itch:
“Designing A Better Design Handoff File In Figma,” Ben Shih
“Code Documentation, Streamlined,” Atila Fassina
“How To Automate Documentation Workflow For Developers,” Portia Burton
“Better Documentation And Team Communication With Product Design Docs,” Ismael González
However, in brief, here are a few of the key benefits of documentation.
LESS TECH DEBT:
Our decisions tend to be much more solid when we have to write them down and justify them as something more formal than self-effacing code comments. Having clear, easy-to-read code is always something worth striving for, but supporting documentation can give essential context and guidance.
CONTINUITY :
We work in an industry with an exceptionally high turnover rate. The wealth of knowledge that lives inside someone’s head disappears with them when they leave. If you don’t want to reinvent the wheel every time someone moves on, you better learn to love documentation. That is where continuity lies.
PREVENTS NEEDLESS REPETITION :
Sometimes things are the way they are for very, very good reasons, and someone, somewhere, had to go through a lot of pain to understand what they were.
That’s not to say the rationale behind a given decision is above scrutiny. Documentation puts it front and center. If it’s convincing, great, people can press on with confidence.
If it no longer holds up, then options can be reassessed, and courses can be altered quickly.
Documentation establishes a set of norms, prevents needless repetition, allows for faster problem-solving, and, ideally, inspires.
Two Worlds:
In 1959, English author C. P. Snow delivered a seminal lecture called “The Two Cultures” (PDF).
It is well worth reading in full, but the gist was that the sciences and the humanities weren’t working together and that they really ought to do so for humanity to flourish.
To cordon ourselves off with specialisations deprives each group of swathes of knowledge.
Although Snow himself conceded that “attempts to divide anything into two ought to be regarded with much suspicion,” the framing was and remains useful. Web development is its own meeting of worlds — between designers and engineers, art and data — and the places where they meet are where the good stuff really happens.
A COMMON LANGUAGE
Web development is a world of many different yet connected specialisations (and sub-specialisations for that matter). One of the key relationships is the one between engineers and designers.
When the two are in harmony, the results can be breathtaking. When they’re not, everything and everyone involved suffers.
Digital design needs its own language: a hybrid of art, technology, interactivity, and responsiveness. Its documentation needs to reflect that, to be alive, something you can play with.
It should start telling a story before anyone reads a word. Doing so makes everyone involved better: writers, developers, designers, and communicators.
Design documentation creates a bridge between worlds, a common language composed of elements of both.
Design and engineering are increasingly intertwined; it’s only right that documentation reflects that.
Design Documentation:
So here we are. The nitty-gritty of design documentation. We’re going to cover some key considerations as well as useful resources and tools at your disposal.
The difference between design documentation, technical documentation, and a design system isn’t always clear, and that’s fine. If things start to get a little blurry, just remember the goal is this: establish a visual identity, explain the principles behind it, and provide the resources needed to implement it as seamlessly as possible.
What should be covered isn’t the point of this piece so much as how it should be covered, but what’s listed below ought to get you started:
The job of design documentation is to weave all these things (and more) together. Here’s how.
MAKE ITS CREATION IS A COLLABORATIVE PROCESS
Design systems are big tents. They incorporate design, engineering, copywriting, accessibility, and even legal considerations — at their best anyway.
All of those worlds ought to have input in the documentation. The bigger the company/project, the more likely multiple teams should have input.
USE DYNAMIC PLATFORMS
The days are long gone when brand guidelines printed in a book are sufficient. Much of modern life has moved online, so too should guidance for its documentation.
Happily (or dauntingly), there are plenty of platforms out there, many with excellent integrations with each other.
Potential resources/platforms include:
There can be a chain of platforms to facilitate the connections between worlds. Figma can lead into Storybook, and Storybook can be integrated directly into a project.
Embrace design documentation as an ecosystem of skills.
Accommodate agile, constant development by integrating your design documentation with the code base itself.
The Mailchimp Pattern Library is a good example of this in practice. Use cases are woven right into the documentation, complete with contextual notes and example code snippets, making the implementation of best practices clear and easy.
WRITE WITH USE CASES IN MIND
Although the abstract, philosophical aspects of design documentation are important, the system it described is ultimately there to be used.
Consider your users’ goals. In the case of design, it’s to build things consistent with best practices. Show readers how to use the design guidelines. Make the output clear and practical.
For example,
How to make a React component with design system fonts;
How to choose appropriate colors from our palette.
As we’ve covered, the design breaks down into clear, recognizable sections (typography, color, and so on). These sections can themselves be broken down into steps, the latter ones being clearly actionable:
What the feature is;
Knowledge needed for documentation to be most useful;
Use cases for the feature;
Implementation;
Suggested tooling.