All you need to know about creating robust design docs
This article is an offline write-up for a remote masterclass I conducted for UX Pakistan. If you feel this is something you and your team can really benefit from, feel free to reach out and let’s collaborate.
Design documentation (a.k.a design docs) has been something which I strongly feel is not talked about enough within the design space. This is an attempt to create a design doc to document how to create a design doc (I know… this is very meta.)
Important note:
While researching on the topic, I came across a lot of content around written case studies for individual projects. While there is some overlap between these topics, I would highly recommend you don’t read this write-up with that expectation.
This is primarily targeted for anyone who’d like to keep track of their thoughts and process. This is not necessarily for your portfolio (but can be packaged to do so.)
There’s a lot of material available on case studies documents. I personally love this essay (linked below) which I highly recommend you at least skim through and see if that’s more relevant to what you were looking for.
Anyways, coming back to creating a design doc, let’s get started.
Purpose
While working with different teams to create products and services, I always felt a LOT of context slipping through the cracks. There wasn’t single source of truth. As a consequence, it was highly likely that some aspect got overlooked in the final deliverable.
“The purpose of design docs is to record how you got to a possible solution.”
Wait… documentation in design?!
If you search google for the terms design and documentation individually, these are what you received as results:
Based on the definitions you saw above, the simplest way to understand the purpose of design docs is to record how you got to a possible solution. This is a general definition, which can swiftly be tailored to the needs of your projects.
But… why would I need to document this journey?
Good question, I highly recommend to utilise this as a powerful tool to gather your thoughts in a single space. This will improve the way you work, and in parallel help you become a much better team player. I’ve also broadly used it for various other reasons, some of the major ones being to:
- act as a living document to align stakeholders
- document key decisions
- share progress with broader leadership
- document the project as a case study for future reference
- create a single source of truth of updated (design) decisions
- improve collaboration amongst your (cross functional) team
… and the list goes on. As some of these may suggest, there is no ‘right time’ to begin documentation. The sooner you begin, the better.
Okay, i’m interested. How do I begin?
Don’t worry, the rest of this write-up will enable you to create a doc on your own and attempt to break it down to keep it focused on the core elements.
Note: This part of the masterclass was very tightly coupled. The crux of the exercises were wrapped up within an hour and leaving the rest of the time for reflections + questions.
There were ~11 participants so we made 3 teams and they collaborated amongst themselves to get this done. The audience was a mix of designers + developers + business folks.
Phase 0 — Prelude: An ‘extremely realistic’ situation
Let’s imagine that you and your friends are part of team which creates digital products and services for a living. Your best friend’s uncle’s neighbour knows your team and gets you a project.
The scope is to redesign a mobile app. Introducing the latest startup to takeover the messenger space; YOLO Messenger!
Disclaimer: For the purpose of the masterclass, I created YOLO Messenger. I created this fictional app to give participants a problem space they are familiar with. I put a lot of effort to ensure it looks really out of place.
Expectations from your team:
- Evaluate the current app
- Quick competitor research
- Compile feedback
- Redesign their UI
- Recommend next steps
Side note:
The expectation for the masterclass was to not spend too much time the specifics of the redesign. The teams had to go through these phases and collaborate their way to create their own documents.
I experimented with creating a sandbox on Figma to get everyone onboard. We used a few tailored components to really collaborate and track key information almost like a virtual whiteboard.
Phase 1— Setting up the core (10 mins)
- Begin by opening your go-to word processor. We used Google Docs for our masterclass as it was a free. (I highly recommend a cloud based solution to support multiple editors in parallel.)
- Add key headings to your document. Then add a few lines of description for each section, to summarise the context which you have so far.
Some headings you can take reference from and rephrase and re-arrange:
- Title — Don’t shy away from making it witty
- Purpose/ Project scope/ The ‘why’
- Team breakdown / contact details
- Current state of project/ context of the situation
- Competitor / Inspiration
- Proposed solution/ Latests draft
- Useful links/ Source files/ Code repo
- Sandbox/ Workspace/ Raw data
Once your document’s setup. Adding few lines to describe each section will spark a lot of ideas. It will get your team to start adding anything useful for additional context.
Phase 2— Deep dive into the current situation (10 mins)
The next step is to collect everything you know about the current state of affairs. For example, the teams used this time to compile their thoughts about YOLO messenger. They documented what were some clear problems which they could see and added notes. This included issues ranging from contrast ratios all the way to typos.
To bring this to your own workflow, begin by literally penning down all your thoughts on the subject. This will enable you to identify blind spots and form connections within the space. You can also go a step deeper and include current metrics and anecdotes of feedback data. Feel free to add related reading which would be great for any stakeholder to get a gist of the problem space.
Phase 3— Research and Inspiration (10 mins)
This phase required the teams to spend researching competitors, their interactions and interface. It’s important to have a good understanding around multiple problem spaces. For this purpose, inspiration boards are a great fit to spark a lot of fruitful conversations. Some links which you can also use for finding references:
The idea here is to probe a lot of possibilities and get familiar with the problem space. This includes what others (including indirect competitors,) might have already solved. In reality, the end discussion of course is also a lot about feasibility, amongst a lot of other topics. Participants discussed and debated what they’d like to include in the doc. As a single unit, the teams explored what the future of YOLO could look like.
One key point was that any reference (image/ gif/ video etc.) which went into the document needed a one liner. This could be a quick summary of why the editor felt it’s a good fit for the document followed with other details.
Phase 4— Laying the foundations (10 mins)
This was when things got really fun and we went analog. Participants now had use the next 5–7 minutes wireframes of the revamped interface. The limitation was to stay away from software and stick to paper + pencil. The idea here is to focus on iterations. Teams used this time to document various approaches in their proposals.
Participants uploaded their suggestions to the master documents. Documentation ensures that teams consider multiple perspectives. This also ensures everyone on the team has an equal voice. It’s vital to also add a brief description to the suggestion for better context.
Phase 5— Regroup and sift things up (5 mins)
Teams gathered again and this time to debate to come up with final variants. It’s important to highlight that it was NOT necessary to come up with 1 final design. The teams could document as many variants as they’d like. As long as the approaches were different and backed up by rationale, it is fine.
The practical use of this particular phase is pretty relevant. Mentioning the advantages and disadvantages of each approach always adds value. Use the same principles to breakdown even something grand as entire navigation experiences.
Phase 6— Showtime! (10 mins)
The final phase in the masterclass was to add finesse to the document. The document can be raw and a work in progress, but it needs to be scannable. Teams spent a few minutes proofreading and stylising the document.
Senior stakeholders , including leadership usually have a pretty tight schedule. So it needs to be structured in a way where you can can walk an executive through the doc in 2–3 minutes. They can then follow up and read the relevant sections on their own when they choose to do so. These documents can be a great avenue to get the right attention
Some tips to double-check during this phase. A lot of this basic principles and is echo’ing the pointers mentioned in the very beginning:
- Proofreading the document
- Making sure it tells a story
- Mention things to be done/ next steps
- Don’t forget to give credit to your team
- Optional: Notes to developers
- Optional: Essential links to prototypes/ flows/ other group activities
Once the teams were ready, they presented their documents. Followed by opening the floor for question and sharing reflection. It was motivating to see the amazing progress made in less than an hour of intense collaboration.
View the final PDFs and snippets from their final presentations here.
“Think of yourself as a museum curator. You don’t necessarily create any content. Your role is to maintain harmony and ensure everyone’s on a single page, literally.”
Encore — A quick overview of the various design docs
This section wasn’t part of the masterclass. It is an attempt to jot down a few types of docs you may create to keep track of the amazing work you do. This is based on the docs I’ve created and the feedback I’ve received in the past.
Important note:
I’ve intentionally not created template doc files. I highly believe the individual themselves would discover what works for them best. The cheat sheet in the end of this section can be a good reference point to have. Your document can of course be a mix of these or even all of these combined.
The 101
The go to format which will really support you and your team to get everyone on the same page, literally. This is one of the first things I do when I’m introduced to a project where there was no form of design doc before. Usually includes a lot of snippets from different documents/ presentations/ recordings etc.
It’s important to keep a healthy list of all useful links here. This is followed by the progress which your team makes as you get more details and work on the solutions.
The full picture
This is a breakdown of a very complicated project spanning across a lot of different teams. These kind of documents also work best to give a new joiners an overview. This gives them enough context on the problem space to get them an idea of the beast they’re dealing with. This one is well suited for a lot of stakeholder management and getting feedback from all teams.
The workspace
The most common format which I use. It’s perfect I just need to document a lot of complicated use-cases but still maintain the context. The need for this came about because none of the design tools solve for preserving context. At the same time, docs are flexible enough to be shared/ edited by multiple stakeholders. This includes interfaces which might have 5–6 different form of data types/ and a lot of sub-flows. Feel free to take snippets from your Figma/ Sketch etc file and plug them directly inside the doc. (These can also be used as the core doc for developer notes and handoffs)
It’s best to keep everyone on the same page and updated with the most recent designs. Maintenance for these is manual, and you’re not accountability to keep it 100% updated. Once the core of the project is complete, it’s natural for things to become outdated.
The incubator
Best document type for anything which doesn’t exist as of today. It’s an extremely dynamic workspace with a lot of thoughts floating around. A wealth of wisdom will be gathered as a lot of people will get tagged for feedback and discussion. It’s great to collect all useful references in a single page to support with ideation. This can also overlap with documenting service design and user research activities. Different data points can be plugged together to make sense of the bigger picture as a whole.
Conclusion
Conducting this masterclass was a great experience for me. The biggest reflection for me? As designers, we dive straight into the solution or ‘sprint mode.’
One key reflection from a bunch of folk was that this enabled them to systematically take a step back. Design docs enabled them to look at other aspects of the product which may get overlooked.
I had a lot of fun and from the feedback I got I’m happy to report that folk found it useful as well (I can only hope they didn’t lie.)
If you found this article useful, I would really recommend you share it with others. It’s about time we get into a habit of penning down our thoughts. Hopefully, our peers will also begin to see this as a valuable addition to the team’s way of working.
