Design is not the end product
If you’re like me, you probably experienced getting the most recent build of your product from the development team, and realising that they missed the point partially or maybe even completely. The logic I spent days or weeks to figure out was not implemented correctly.
Most of my time as a designer is spent creating visual design. I think about every little mechanism and feature, figure out how they work best, try out numerous different variations, test it with users, iterate, iterate, iterate.
But despite my tireless effort to create something great, I still end up with this broken build. Because all I gave my development team was a link to a Zeplin project, with fancy overviews of my style guide and components.
Now, nothing is wrong with a good handover of visual assets.
But screen designs are a horrible format for a handover. And since it’s way easier to simply make things right in the first place, we need to find a way to avoid making mistakes.
Our solution ended up being documentation.
How do I get started with documentation?
As designers, we build systems and logic in order to structure information and features, and help users reach their goals. These systems and logic are the very core of the products we build, that’s why it is our responsibility to support our development teams to build solid software.
We need to explain the logic in the simplest way possible. With words, tables and visuals, if it’s needed. Take your time to explain it in the simplest, most systematic way possible. By doing so, your developers will be able to understand the logic before they try to figure out your visual designs.
As a bonus — writing documentation will also help you uncover the full scope of the feature you’re building. It might show flaws in your approach, or help uncover unnecessary complexity.
Heres a few guides that can help you get started:
Data Models
Define the data structure of each data model in the product.
A data model can be a User, Post, Category, etc.
Create a table with the data related to the data model. I usually start with Key, Type and Example.
For a user that could be:
In some cases you might need to refer to other data models in your documentation. These data models should be defined separately, so you can easily reference them by name or a direct link.
For example:
It’s important that the formatting of data is clear. Make sure to be explicit on things like Dates, Time Stamps, etc.
For example:
Core Concepts
Describe the core concepts and terminology used in the product. Often, there is a lot of logic tied to terms that might seem insignificant in a visual design.
By describing each concept separately, and their relationships, we ensure that everyone understand the concepts deeply.
Collections
Describe lists of categories or similar collections, and the difference between the items in the collection. This could be things like Categories, Challenges, Price Tiers, User Ranks, etc.
Visuals
If a data model or concept are directly related to a visual asset you should link to the design or add an image in the documentation to make the link clear.
This can also be done for entire product epics with descriptions of the purpose of the epic.
Navigation Structure, Flows and User Journeys
Communicating flows and the relationship between screens are done best with flowcharts (Whimsical is great for this) or prototypes (Figma, Sketch, Invision all do this).
It’s very important to clearly show the Navigation Structure, not just a spider web of linked screens. Take your time to distill the navigation down to it’s core, making it simple to digest and document each flow separately.
Decisions
Sometimes a feature lies dormant for months until it’s back on the roadmap. In this case, it’s important to document decisions that where made during the design process.
Gather decisions and the reason behind them as you go. This will help avoid repeated discussions that where previously discussed.
Where do you keep the documentation?
Theres plenty of tools out there to write wiki’s and documentation. Most of them pretty similar. So which one you choose is really a matter of preference and convenience.
My team and I have been using Confluence for years and it’s really the perfect fit for our needs.
Heres a few products that I have tried:
- Atlassian Confluence
- Notion
- Google Sheets
- Azure DevOps
Did I miss a killer tool? Leave a comment with your favourite!
I hope this can help you start your documentation and improve collaboration with your team. And it is a collaboration. So get your team on board, everyone can contribute. Documentation should be a living document and it should foster more conversations and discussions. In the end, it’s not just a powerful tool for developer, but equally so for designers, project managers and strategists. It becomes the single source of truth for your product team.
Full disclosure, I’m no expert. I just tried a bunch of things and kept doing what worked for me. But if theres one thing that I know for sure, it’s this:
