Design Specifications Template
How a Design Specifications Template simplified and gave consistency to our team's communication with engineers and product managers.
Why develop documentation guidelines and templates?
Different initiatives happening simultaneously, different teams, and ways of communication are challenging not only to designers but also engineers and product managers. We struggle to communicate effectively and durably.
As designers, we felt that it was sometimes hard to remember all the decisions and details of a solution when you have several initiatives at the same time. Adding to that, if you went on holiday or any absence, it would mean that you had to spend a lot of time passing information and making the other designer understand your own file/frame organisation — only to miss the exact info that was needed during your holidays.
We were also aware that product managers faced the same problem: every new idea or significant chance would have a new confluence page, and the number of pages around the same initiative would grow and grow into a pit of descoped pages hard to navigate.
Engineers work with designers with different communication strategies and different organisation of deliverables. They rely on the prototype but still feel a lot is missing from our side.
Documentation guild
My colleague Carla Cabeça was the driving force behind a new guild — the documentation guild. She wanted to structure our communication and help facilitate the conversation around initiatives with efficient and consistent documentation.
She brought me and our colleague, Teresa Mouro Pinto, to the guild and road mapped our work starting with a discovery based on stakeholder interviews— she wanted to make sure that our work would serve most needs and fit the different ways of working. Our manager and team were thrilled with the potential outcomes.
Discovery
We prepared a series of interviews with stakeholders to understand how project and design documentation is received, interpreted and used and potential pains and solutions.
After the interviews, we summarised findings into a matrix that organised each stakeholder role (designer, PM and engineer) into their specific pains, needs and opportunities.
From this work, we could map the needed documentation, template or guideline. But since we were only three designers working, we created a prioritisation map to help focus on what we could do now — the solutions with higher value but lower effort.
One of the solutions was a design specifications template, and I was the one responsible for taking that work further.
Why a design specifications template?
Because of the lack of time to prototype in high fidelity, some vital information would usually be missing when it was delivered to engineers:
- Micro-interactions
- Sad path
- Edge cases
- New copy or changes (especially in tooltips)
- The business logic behind each component
Some of these ideas were already discussed but not registered. A written document could help describe some of the needed information while maintaining the prototype as the main deliverable of design.
When development starts, some technical constraints or even new or changed requirements from businesses or users might need to be addressed in the solution. We meet to talk about it or use the initiative slack channel. This means that besides the project issue or story that might come from that trade-off conversation, the design specifications for that change were integrated into the prototype without context or rationale.
How to create this template?
So I've already worked on a similar idea on an initiative focused on redesigning an entire tool to use our new design system. I took this opportunity to test the current tool and analyse potential experience improvements that could be done to it.
A detailed explanation of each component's behaviour and logic was crucial to be sure that the integrity of the tool's main task was not compromised during this transition. Still, the experience was (in small but visible ways) improved.
My manager also had some great documentation for a tool she designed. So my first step was to map everything that works on these 2 cases and merge it with the needs of designers, engineers and PMs we gathered from research.
Design Specifications Template
For this article, I created a Notion file with the template without some specific complexities of our organisation.
This template is for work already presented to engineering.
We found that the best time to work on these is after the prototype is presented, before the beginning of development.
Bare in mind that this template is flexible and new info can be added depending on the use cases for each project. Remove the sections that don't make sense in your case. Everything in grey are instructions for possible text, delete it and replace it with your own words.
Template structure
The template is divided into eight sections:
- Intro
Intro has a summary of the initiative and a couple of short sentences that explain the initiative's main goals and aims in the context of user experience. - User journey
It maps the user journey inside the global user journey within your product. You can also add flows and other tools that help understand how the initiative fits into users' tasks.
Try to add sad paths or at least high-level solutions to them. - Prototype & Pages
Add the Figma file here and any instructions related to navigating it.
You might want only to have the prototype itself or the entire file. It depends on our needs — be sure to explain the link you are sharing and how to use it. - Component breakdown
This is the most extensive section, dedicated to breakdown a page or component and explaining it component by component (if necessary).
It's good to reference design systems, copy, business or technical logic, sad path and errors, etc.
A good way to not fill the page with info is to hide it behind toggle lists or collapsable boxes.
Any change or essential info should be called prominently so it's not lost (and should also be referenced on the changelogs below). - Copy
New copy or changes to the existing copy are essential to highlight. We used to work with a copy team, and even when you don't have that help, it's crucial to have this section.
Identify copy's location on the prototype and why it's essential.
This section can be extended to any content outside the UX design domain: illustrations, new icons, etc. - Research findings and data
The findings and data already informed your work but might be helpful to argue and discuss the current prototype and solution or even to inform future work.
Having all research findings (or other discovery work) close to the design solution is always helpful for you and engineers and product managers eager to learn more about it. - Changelogs
Since this documentation is done right after presenting the prototype to engineers, it's good to keep track of all changes done after they start developing. Date, people informed provide accountability, but the rationale is important to keep the conversation open. - Questions
This document is shared by many people and should be a working document that facilitates communication. With that in mind, a section for questions is great to keep it open and improving.
Implementation and impact
Along with other work within the context of the documentation guild, like guidelines for designers or PMs and Initiative templates, it is being implemented by our team.
It’s true. It takes some time and dedication from designers. Not everyone enjoys the exercise, but we are still doing it — it has proven its value. The designers that have done this all feel more confident in their deliverables and see the positive impact of their work not being lost. Information persists, and they can go on holiday knowing that all information is available to everyone.
This template, however, is not written in stone! Each designer adapted it to their needs — some need more space to detail the user journey, others a more comprehensive guide on components breakdown. Significant updates on an initiative might need to be treated as a new section or a sub-page, and research might need more space. The structure is consistent across the team, making it more efficient and effective to communicate across the organisation.
Thanks to my amazing 🌟 colleagues Carla Cabeça and Teresa Mouro Pinto. And everyone else joined the guild after, doing work that impacted other teams besides ours in a true spirit of sharing and collaboration.
