Why you need design documentation

Think back to the last time a stakeholder asked you a question about a past design decision. Maybe why you went with a different hover state for that button, or why you decided to choose typeface A over typeface B. How deep did you have to dig into your mental archives to come up with the answer? Did you even find it? If you’re anything like me, the answer you gave sounded a lot like ¯\(ツ)/¯

With every design project, we make a thousand small decisions and a dozen big ones. We choose one direction over another, we try variations and we narrow them down, we share with our teams and we reach a consensus. Those decisions represent hours and hours of work. But the context behind them and the work we put in to reach consensus is all too often lost, buried in Slack or lost in the ether after a Zoom call. And what happens when you move to a new role, or one of your teammates does?

At the time, the “why” seems so clear and so obvious that maybe we assume we’ll have no trouble recalling. But can you even remember what you had for breakfast yesterday? Me neither.

Build design documentation that works for everyone

So what exactly does good design documentation look like? We can take a lot of cues from our peers in Product and Engineering. A well-written project brief starts with a Problem Statement, and that’s where your design document should start as well. Stating the problem we’re trying to solve up front helps center us and our audience on the user need, not the feature we’re shipping. Pro tip: starting your design critiques with the problem you’re hoping to solve is a great way to get everyone aligned!

Goals or outcomes are a good next step. How will you know when the problem is solved? What customer behavior will change, and how will you measure that? Not only is this good documentation, but it’s an important mindset shift for design. Our purpose shouldn’t be shipping a thing. So if you know what the user problem is, it’s just a hop, skip and jump over to defining the outcome when that problem is solved. For instance, if I know that users are having trouble finding the “Add to Cart” button, I can extrapolate from there that a successful outcome of making the button more discoverable would be more users clicking that button. If you’re interested in learning more about this topic, Josh Seiden has a great book on it. You’ll also want to capture the Success Metrics that will tell you when you’ve achieved that outcome, whether that’s a 5% increase in button-clicks or a 10% decrease in support tickets.

Maybe you don’t have all the answers just yet, and that’s where an Open Questions section comes in handy. This is a great time to identify all the gaps in your knowledge, list them out, and reach out to your stakeholders and partners to enlist their help. Maybe your Support team needs to help you understand what percentage of ticket volume decrease is realistic. For me, this is often where I start to identify areas that need the superpowers of our user research team. The double bonus of listing out your open questions early is that a) you won’t get caught by surprise later, and b) your stakeholders get invested in the work early on.

Don't forget tech and scope

Technical Requirements are another key piece of your documentation. Unless this is a blue-sky project, the odds are good that there are some boundaries you’ll need to work within. Capture as much of this detail as you can on your own, and then loop in your engineering partners to help round it out. Just like the previous section, there’s a twofold win here of less confusion & more buy-in from your team.

Lastly, think about anything you know you won’t be doing as part of this project and collect it in an Out-of-Scope section. If there are areas of your product or a set of edge cases that you know are not up for considering, list that out here. If you’re not sure whether something is in or out of scope, that’s a great candidate for your Open Questions.

I know, I know. That’s a lot of writing, and you haven’t even gotten to the designs yet! Good news — that part comes next. Whether it’s flows, wires, or mocks, bringing those back to your design document through links or embeds provides you with a perfect “hub” for the project. Capturing each stage of the process with artifacts in one place creates a powerful narrative, plus it avoids the pain of digging through Figma, Slack or email when you need to revisit something.

This hub you’ve created with your design documentation is now the perfect vehicle for sharing your work with stakeholders and leadership. They’ll have all the context they need to understand your decisions, allowing the conversation to focus on the work itself. And if you can capture feedback and conversations in this same spot, you’ll have everything you need six months from now when you’re scratching your head and saying, “So why did we go with this hover state for the button?”

‍

If you're interested in improving the Design documentation at your organization, see how Notebooks can help.