Illustration by Fanny Luor

How do you design a design doc?

John Saito
Dropbox Design
Published in
7 min readFeb 28, 2018


When you think about design, the word “documentation” probably isn’t the first thing that comes to mind. But documentation is a key part of the design process for many teams.

In a casual Twitter poll, 1 in 3 product designers said they spend at least 25% of their time reviewing or writing documentation. The funny thing is, many design classes don’t even talk about documentation.

Yeah, I know a document isn’t as sexy as an interactive prototype, but a design doc is where ideas can grow quickly. It’s where thoughts morph into words, and words blossom into solutions.

When done well, a good design doc can:

  • Help you organize your thoughts
  • Solidify your point of view
  • Rally your team around a goal
  • Explain the why, not just the how
  • Prevent time-sucking debates
  • Make a developer’s life easier

At Dropbox, we make design docs for every project. All projects need to start somewhere, and for us, it often starts in a Dropbox Paper doc.

But how do you design a design doc? I asked a few designers on our team for tips on creating documentation. Here’s what I picked up from them.

Connect the docs

Most of the time, a design doc is just one doc in a sea of other project docs.

So one thing Emily Miller does to keep her docs connected is to create an index at the top of her docs. The index shows related project docs, and all those docs have the same index at the top. “It’s like a mini website nav,” explains Emily.

An index keeps it all connected

Let’s say her design doc is called “Project Popup [Design].” The engineering doc and copy doc would follow a similar naming pattern: “Project Popup [Eng]” and “Project Popup [Copy].”

It’s a quick trick that goes a long way in helping her team find all related docs quickly and easily.

Embrace emoji

A lot of people use emoji nowadays in messaging apps. At Dropbox, we use emoji quite a bit too — in our design docs 🤓

Emoji isn’t just for decoration. You can use emoji to make your doc more scannable, to call attention to specific sections, and even to communicate status.

For example, Sheta Chatterjee and her team use a pin emoji to show the current week of a sprint. They also use an animated digging emoji to show if a section is still being worked on. If others see the animated digging dude, they know those designs aren’t set in stone just yet.

Emoji isn’t just for decoration

Some designers on our team also use emoji in the title of their docs. In Paper, if you add an emoji to the beginning of your title, that emoji will become the favicon in your browser tab. The emoji makes it easier to spot that doc — which comes in handy if you have a million tabs open at once 🙈

Ah, there’s my doc!

Relive the experience

A lot of times, designers aren’t creating new products from scratch. Instead, they’re making tweaks to existing flows to make them better.

Before putting together any wireframes or mocks, Sara Lin goes through existing flows and documents everything she sees. You can say she’s reliving the experience.

She documents all her thoughts in an audit doc, which she links from her main design doc. In her audit doc, she recreates the user journey using screenshots of the existing flows. She then adds detailed commentary about what’s good and bad about each step in the flow.

Documenting the good and bad in an audit doc

Sara says doing an audit helps her get into the mindset of the user, and that helps build user empathy. These audits remind me of Samuel Hulick’s user onboarding teardowns, but imagine doing it on your own product — where you can be your own worst critic.

Spin up a story

As I skim through Laura Barbera’s design doc, I stumble upon a story. It’s a gripping story about a medical researcher named Corrine, having a tough time at work.

The story touches on topics you might find in a Hollywood movie. There’s talk of big presentations, lost documents, and burnt bagels. There’s a conflict, climax, and resolution — you know, things you’d find in any good story.

To make things more interesting, Laura also spices things up with a few pop culture references here and there.

A story helps make your design more convincing

Laura uses stories like this to help explain her designs. It’s not about User A with Problem X. It’s about a person in a real situation with real problems. The story helps make the problem and solution more convincing.

Get ’em hyped

“Docs can help people get excited about an idea,” Ryhan Hassan tells me.

When I ask him what he means by that, Ryhan explains how he sometimes uses design docs as a presentation tool. He shows me a few docs that are light on words and heavy on visuals.

In these docs, you’ll find all sorts of visual artifacts: photos of sticky notes, screenshots of chat conversations, sketches, video clips, and even Framer prototypes. They’re all embedded in his Paper doc — to help his ideas come to life.

He stitches together different types of visuals to create a narrative that he can walk through during a presentation.

Photos, chat conversations, and sketches help tell the story

“It’s easier to build momentum if others get excited about it,” says Ryhan. With the help of visual artifacts, those big floaty ideas feel a lot more concrete and compelling.

Leave a paper trail

No matter how amazing your design chops are, others will always have questions about your work. Why did you use that component? Have you considered X and Y? How does this interact with that other feature?

You can save yourself a lot of hassle by documenting the thinking behind your designs. When done well, documentation helps everyone on your team understand how you got to your solutions. Good documentation is especially helpful if you work with remote teams.

For Melissa Mandelbaum, good documentation is all about “creating the best possible paper trail you can.” When creating design docs, she includes multiple design proposals, along with pros, cons, risks, and open questions for each proposal. This shows the design was done thoughtfully, not willy-nilly.

Show the thinking behind your work

“Spend a little more time upfront documenting your design decisions. It’ll always make it easier to discuss and review the decisions,” Melissa points out.

Build a graveyard

As a designer, sometimes you might try tons of different explorations before settling on a final direction. But you don’t want to scare off others by listing dozens of explorations, right? So what do you do?

Kyle Decker digs up a doc he calls “Design Graveyard.” In the graveyard are dozens of old designs from his past project, along with notes to himself. The notes explain why certain explorations didn’t make the cut.

The Design Graveyard—where some of your best ideas lay to rest

Kyle keeps these old explorations separate from his main design doc to keep his main doc clutter-free. But his old explorations are just a click away in case he needs to bring them back to life someday.

Whatever you do, don’t throw away your old designs. Yesterday’s dead designs might just become tomorrow’s saving grace.

Find a partner

A great thing about a design doc is that it becomes a place where you can easily collect feedback about your designs. Teammates can leave questions (and compliments!) using inline comments.

But if you’ve ever collected comments in a doc, you know that feedback can be both a blessing and a curse. At some point, you’ll need to share your designs with a larger group, and not everyone will see eye to eye.

In these situations, Wes O’Haire recommends finding a partner first. Before you share your doc with a larger group, share it with one person in that group first. Walk that person through your doc to make sure everything makes sense. That way, when you’re ready to share it with the larger group for approval, you already have one person on your side.

Get one person to review your doc before everyone else

Thanks to Wes, I now know that the way you share your doc can be just as important as the content inside it.

How do you do documentation?

After chatting with these eight designers, I learned there’s no single way to do design documentation. Every designer has their own process, but we can all learn a trick or two from each other.

Now that you’ve seen some of the techniques we use, we’d love to hear about your tricks of the trade, too. Feel free to leave a comment below if you ever feel like sharing tips on documentation. We’re always eager to learn something new.

And if you’re interested in connecting with the designers mentioned up above, you can find them here:

Want more from the Dropbox Design team? Follow our publication, Twitter, and Dribbble. Want to make magic together? We’re hiring!



John Saito
Dropbox Design

Design at Snowflake. Always chasing rainbows.