As designers, we create solutions to problems. As designers, it’s also important for us to keep the entire team on the same page with our solutions, and make sure that other people understand the thought and the implementation of designs.

Design docs helps us bridge that gap between different teams and to keep everyone aligned. I have iterated and worked on documentation for a while now in HyperTrack. The tool you use and the format you follow is gonna be different with your team as compared to mine, but I wanted to share my learnings over creating such a doc …

Create a single document

Keep all the context in a single document. You may divide documents by clients, features or products, but it becomes important to keep all the information for a single solution in one place

Initially I split different sets of documentation in different places. Documentation for developers was in GitHub, user research was in Notion, some animations were in Dropbox or Framer cloud and then there was a google doc that explained the feature and it’s usage. Getting them all in one place makes it easy for you to track and for your team to refer to whenever they need it

So I started to put them all in a single Dropbox Paper document. Unfortunately, there is no single tool to solve all of the above use cases. So we were still using different tools but this doc acted as a starting point for everyone in the team.

Table of contents

As the document grows, it becomes more complex and might have more sections in them. Different people in your team would end up following this doc as well over time. Putting a table on top would help them easily go to the information they were looking for. This would also link to any external tool that we are using.

Screen Shot 2019-04-01 at 11.34.08 AM

Think of all teams

Shipping a good experience requires involving multiple teams together - Developers, Content writers, Designers, Product managers and more …

Try to make sure that your document addresses everyone involved in the team and make sure that the discussions and updates are limited to the same document. The structure of my document goes like :

  • Index table - Includes links to all other documents
  • Insights from user research - I include the insights from user research to establish customer context of the feature
  • Empathy diagram - This table lists tackles the emotional aspect of the user while using the feature
  • Jobs to be done - It’s important to abstract out the research and users’ insights into simpler tasks that the user would want to perform. This is usually the most critical part of the document, as it establishes in simpler terms what is that the user wants from using this feature
  • Designs - While zeplin is good for developer handoffs - there are still aspects of design that can’t be handled in Zeplin. Things like the default states, different permutations of the same screen, edge cases etc need some sort of written documentation to go with them, and all of them might not be visual in nature
  • Animations - I was using Framer and Principal for showing animations. Both of them are good in their own ways. Videos exported from these would end here.
  • Flow diagrams
  • Copy versions - Sometimes a single

Always updated

If your document does not become the single source of truth, then other people might stop using the document, take discussions in other more active channels or even start creating their own versions of documents.

A lot of discussions might happen in other places as well outside the context, phone calls, slack discussions, emailers etc. At the end of the day, we have to make sure that the decisions end up in the document at the right place, and that the entire team can trust this document.

Bonus add a line on top saying when it was last updated. 3