.svg){kind=logo}
Menu
Close
When done right, design documentation can add real value to an organization. It aligns the team on objectives, streamlines the handoff process, and makes it easier to work on future user experience (UX) projects.
Sadly, a lot of design documentation is a bit far from great. According to the 2023 DesignOps Benchmarking Report, 66% of design and development teams think poor design documentation is the main cause of design-to-dev inefficiency.
This makes sense. Sometimes the documentation is too complex, too detailed, and developers and stakeholders don’t read it properly. And sometimes it isn’t detailed enough, leaving people with questions. Either way, bad design documentation leads to unnecessary back-and-forth, misunderstandings about design intent, and delays getting features released.
So let’s figure out how you can create design documentation that gets everyone onboard and rowing the same way.
Then we’ll look at a design document template for creating UX documentation that engages and inspires all stakeholders.
Design documentation is a collection of information about a specific design project, e.g. a new screen, feature, or process within an app. It covers the problem to be solved, the objective of the new design, and how it should be implemented. And it can include everything from end user profiles to roles and responsibilities to finished designs.
Design documentation serves a bunch of purposes within the product development life cycle:
Design documentation is used at the design handoff stage, to provide developers with the specs and context they need to implement a completed design. If the documentation doesn’t include everything the devs need, they will either come back with lots of questions or code something that doesn’t fit what the designer intended. The better the documentation, the smoother the handoff.
Design documentation aims to act as a single source of truth for the project, so that all stakeholders know what’s being done, why it’s being done, who’s involved, how to measure success, and more. It prevents different team members from interpreting the build differently, creating process discrepancies that could affect the usability of a product. It’s also great for transparency and for letting everyone catch up at their own pace.
It’s easy to forget things said or decided in meetings, and important information gets lost if it’s not properly documented. Design documentation provides a history of design decisions and the rationale behind specific iterations. This makes it an essential point of reference when embarking on a future design project.
Good documentation is hard to write, and most designers are much more excited about creating designs than documenting them. This lack of enthusiasm can impact the quality.
But more often than not, quality isn’t the problem. It’s that designers don’t share it properly. They create the documentation without team involvement, then hit publish and hope people use it. And then they don’t.
Design documentation can be beautifully written, nicely formatted, and well-illustrated, but if it’s not used for the purposes it was made for, then it’s all for naught. The worst documentation is the sort that gets ignored.
Now let’s look at 3 tips for making design documentation that’s actively used by the people it was created for.
Designers often attempt to document their designs in design tools like Figma, particularly for handing over to devs. While Figma is trying to make their tool appeal to devs (e.g. with Figma ‘dev mode’), it’s still a tool built for designers, not devs. And it’s chaotic and unwieldy for many devs, let alone other stakeholders like marketing and senior management.
A general team documentation tool is much more appropriate for writing long-form content than Figma’s structureless canvases, which have limited text editing capabilities and poor version control. Confluence, for example, offers hierarchical page structures, full page history, and extensive formatting capabilities, from headings, tables, and lists to expandable sections and code blocks. It also facilitates collaboration with comments, @mentions, and simultaneous editing.
Importantly, there are ways to integrate Confluence with Figma so that you can embed draft, final, and updated Figma designs on Confluence pages. Confluence users will be able to view and download designs without logging in to Figma.
Most fundamental is that documentation tools like Confluence are for everyone. Figma is likely to be inaccessible to most of the team—why would a support person need a Figma license? So an already established info-sharing environment is going to be a much more effective tool for aligning all stakeholders.
People care more about things they’ve been involved in from the outset. If you use your design documentation as a means of gathering feedback on your designs, people are more likely to pay attention to it. It’s a good idea to share documentation with the team even before you’ve mocked up any designs. At this stage, the documentation simply outlines the designer’s objective and the problem to be solved in order to get ideas and insights from others. Keep sharing updated documentation as your designs come together, and as they change.
Confluence is ideal for sharing dynamic documentation, enabling you to interact with team members using comments and @mentions, collaboratively edit pages, and create links between your pages and others people’s.
Moreover, if your design documentation is centralized in Confluence, that makes it easy to involve other teams such as marketing and support in the design handoff process. The Clear View Method for Design Handoff promotes handing over designs to everyone, not just developers, as well as regular meetings and check-ins with all teams throughout the life of the project. Good design documentation should facilitate and support these interactions, keeping stakeholders aligned and making sure designs are continuing to meet user needs.
Design documentation in Confluence is good for big or complex design projects, such as a new login process. But you don’t necessarily need full documentation for minor UX improvements such as rolling out a new button design or adding dark mode functionality.
Long-form documentation can be overkill if it’s created for the sake of it, wasting both the creator’s time and the reader’s. It also makes it less likely that future documentation will be used properly.
If you use Jira, a simple Jira ticket could function as your design document. Simply add the things devs need at handoff, such as context and acceptance criteria, to the issue description. And if you integrate Figma with Jira, you can embed a ready-for-implementation Figma design in the Jira ticket, which your devs can access without a Figma license.
Don’t eschew documentation entirely though. Even the smallest project should be documented, because a chat in an office or on a video call doesn’t provide designers and developers with a history of changes to the product to be referenced later. This could lead to redundancies and duplication in future work.
Here is a template for writing UX documentation in Confluence (or indeed any other long-form content tool).
Our earlier blog has more on how to create design documentation in Jira and Confluence, and what to include in your design handoff document.
Why are we working on this design?
[This year we wanted to focus on making our Collections app more social and giving our users more options to share their pictures and albums. The feature that we’ll be describing in this document is related to our mission to make things more social: social profiles for all users.]
What are we trying to achieve with this project?
[We want to create social profiles for all users to allow them to share their collections with others.
Currently, it’s possible to share collections with others using a link, but with social profiles, users will be able to discover other users' public collections without needing a link.
To enable users to discover new profiles and collections, this project will also include a user search feature.]
How do we measure if the project is a success or not?
[The underlying goal of making Collections more social is to increase traction and popularity. For this update, we will measure success by the number of collections being shared, and the number of visitors to public collections.]
What needs to be done for us to consider this design fully implemented?
[Production version should follow the design as shown in this document. Animations should be added. Dark mode is a necessity.]
What things might seem related, but are excluded from the project?
[In this version, we will only focus on social profiles in the native app, not the web app.
Search will be limited to searching for users, not collections, nor any kind of ‘for you page’-inspired functionality.]
What is the current situation (if any)?
[We currently do not have the ability for users to have a profile or search for other users.]
Who’s part of the project and what are their roles?
What technical limitations do we know about?
[In order to keep the user experience fast, the dev team mentioned we should limit ourselves to showing small images with a max file size of 300kb.]
How and when are we going to test the result?
[As this is new territory for most of us, we will be performing prototype testing as soon as we can test navigating between screens to the search UI and then to the profile UI.
Quality assurance testing should be done as usual: on the test environment and on at least 3 different iOS devices.]
What is the proposed solution?
[Search UI
This screen opens up when the user taps the search icon in the bottom menu bar of the app. By default, it shows you your most recent search queries.]
[Profile UI
This is the screen that appears when the user clicks on another user’s profile. The default state shows how a standard profile should appear. The empty state is what should appear when the user’s profile has no content.]
List the Jira tickets required to implement the design.
Design documentation is an essential part of the product development life cycle and the thing that bridges the gap between designers and everyone else. It’s particularly important for facilitating good developer-designer collaboration.
But if you document your designs in design tools like Figma, you risk overcomplicating the design handoff process and alienating non-designer stakeholders. Create your design documentation in a content collaboration tool like Confluence and you’ll find it much easier to get everyone on the same page design-wise. And using your documentation as a means to communicate with the rest of the team will help keep people engaged and minimize unnecessary back-and-forth later.
But beware of creating too much documentation for small projects. Minimal documentation in the form of a ticket in Jira is fine; not every new usability improvement requires its own Confluence page. At the same time, writing stuff down is the best way of avoiding misalignment.
If you want to create design documentation in Confluence or Jira, with embedded Figma frames users can see without Figma accounts, try Figma for Confluence Pro or Figma for Jira Pro free for 1 month.
A former lawyer, Berry loves theme parks, has published a sci-fi conspiracy thriller trilogy called Million Eyes to rave reviews, and is a specialist in writing content for tech companies.
