Design documentation.
The truth is documentation is a neglected afterthought. Designers want to design first and worry about documentation later and leads to issues as memories do fade and designers often move on. Good documentation is more than onboarding manuals. Design documentation are the source DNA that underpins your design systems, lets everyone know what’s been done, why it was done that way. They are catalogues of decisions, learnings and plans. Should any co-worker have a question, design documentation is where the answer should be found.
Setting documentation up early in the process clarifies requirements and specs before committing money. More often than not gaining stakeholder approval relies on this good quality documentation and neglecting it is pure folly. But more than aligning stakeholder it is also critical in implementation, as a design is usually implemented by others. Design documents mitigate ambiguity and are a manual to reduce questions, mistakes and frustration. Ever tried assembling Ikea furniture without the manual? I rest my case.
From a strategy perspective, design documentation acts as a catalyst for analytics and tracking. Documentation facilitates the insight between what was deployed and the changes in the user behaviour. But sadly design teams often push back on documentation at the outset. Yes time is always limited, yes designers will always want to get to the designing and worry about documentation later. But I have found that teams respond positively and deliver better results when they actually understand why they need to do it and the constraints they need to work within. So here is my guide to getting designers to do boring documentation.
There are lots of tools processes for design documentation. And if I am honest they frequently disappoint. A simple document and straightforward folder structure will trump clever tooling, if you invest in a consistent structure and ensuring edits follow accordingly. I like to use Google Drive and Documents as it reduces onboarding and you can tag and search efficiently. Lets start with the structuring first …
Project overview folder
This folder contains the high-level overview of the program and the goals to accomplish it in a time frame. These documents create alignment and understanding of the purpose and should be both inspiring, and yet achingly simple.
Insights & observations folder
Research and documentations should cover business and customer insights follows a simple structure:
1. Background & context
2. Problem statement
3. Hypothesis
4. Experiment design
5. Results & observations
6. Conclusions & reports
7. Suppositions
Function folders
Functions own their own folders and vary in both form, complexity and fidelity, depending on process and timeline. The golden rule though is to ensure the documents complement, not supplement the design process and are always actionable. Always remember that documents must have a purpose beyond an audit and should enhance and communicate.
Essential documents
Documents depend on the project , however there’s some documents that are common to all …
The overview document
The overview documents should cover both business and audience and technical requirements. I believe having the constraints and assumptions in this folder are beneficial as they impact choices (try to link assumptions to the insights documentations). Alongside the overview and assumptions is the high-level goals to accomplish in the time frame.
The golden rule is any stakeholder should be able to access it and understand in a moment the purpose of the project.
Product requirements document (PRD)
The PRD is the detailed version of the overview document and is the single source of truth for the delivery team. In essence the PRD enables cross functional teams to stay aligned. It’s all too easy for multiple teams to start aligned and fragment and the PRD helps to maintain autonomy and alignment. Further a well written PRD can enable teams to immediately identify what might work and what doesn't and can help teams a vision quickly.
Audience insight documentation
Audience insights (gleaned through research) is the basis from which design decisions will be made in answering the PRD. Nothing and I mean nothing, will beat understanding the needs and expectations of an audience. It also enables measurements such as conversions, activation, loyalty and revenue. However it is easy for an insights document to become overwhelmed by findings but missing insight.
Findings and insights look alike, but are different in terms of content, reliability and durability. I use a simple decision tree to qualify if its an insight that holds enduring value or a perishable finding:
Does it say something about the attitude, behaviour or context of the audience?
Yes
You found and insight include it in the documentation
No
Move to the next question to find out
Is this a fundamental principle that you’ve uncovered, such as behavioural or design pattern?
Yes
You found and insight include it in the documentation
No
Don’t give up and go to the next question
Does this say something about the brand, product or service as whole and not a part of it?
Yes
You found and insight include it in the documentation
No
It really is a finding, but it still might be worth adding…
Insights are on the whole durable and relatable as they are often valuable to other functions, products and services within an organisation. Documenting findings instead of insights generate reams and reams data. But most of the time those findings lose their meaning unless they relate to specific features. Think before you write which brings me neatly too…
Think before you write any documents
Design documentation helps solve a problem and facilitates communication or create a meaningless audit trail. There are important aspects to consider in crafting them:
Be empathetic to your internal audience
Keep in mind needs, interests, and the tone and kind of language of the team and stakeholders. Why not try testing and iterating on a few documents before going all in – you’ll be surprised what you learn. For example I found out the hard way writing a PRD in Sweden requires a very different tone than in the UK.
Documents are living & breathing
Design documentation is not a one and done thing. It’s not an afterthought. You can’t create the documents at the outset. Real documentation is ongoing and used by the whole team – which is why having clear structures and consistent processes are key.
Documents are tools
Good documents are tools that allow us to prioritise tasks. They clear point to the next step in the project, what has worked, what hasn’t and creates a shared sense of direction and project identity. They are not to be filed and forgotten.
Versioning the vision
When a designers says what is the latest version - i die a little. Try using Semantic Version to connect documents to design systems whilst improving collaboration between designers, engineers and project management. I promise it will change your life.
Documents are not just words
Be visual and make it engaging… Try to Include specific components and versioning histories to translate abstract information into visual instructions.
Operator instructions
Detailing instructions for common tasks is really appreciated. For example step-by-step instructions on how to craft a specific component will increase consistency, make onboarding faster and ensure knowledge is not lost and can be really rather fun.
Conclusion
Design documentation are a fundamental part of the design process and should come as naturally as creating a design. If you take care of them, and keep it up-to-date, they will take of you and your team.