Documenting design can be hard, especially under time pressures. It’s harder if you don’t know what good documentation looks like, or how it’s done.
You can use documentation to identify who understands what works in the project context. This can highlight if anyone should be brought up to speed with key learnings, and gives you a way to share them.
It can also speed things up – if you can see your product owner has been aligned with user research in 95% of their decisions, then you might be more comfortable trusting their future decisions. Documentation also holds stakeholders accountable; if they make decisions counter to evidence, you have that recorded.
What good documentation looks like
Illustrating evidenced lines of reasoning for design decisions help anyone needing to understand your work. “Why did we spend three weeks on research?” is easier to answer if you can quickly show the challenges you faced, how you addressed them, and what you learned.
Bringing on new team members is much smoother when you don’t have to personally deliver all the context because you have comprehensive documentation.
There is no simple template for what good design documentation looks like. However, there are some important things to make your documentation serve constructive purposes.
1. One source of truth
You can keep things in Figma, Miro, and various documents, but they should all be accessible from one place. This means when you send one link, everything can be found from there.
Notion or Confluence are great, but even Google Drive can serve this purpose. It just needs to be a platform that’s easy to share with minimal friction. Trello or whiteboarding tools are poor sources of truth, because they’re not easy to navigate, search, or export from.
2. A decision log
In most teams, all a decision log needs is what the decision was, who owned it, why it was made, and who was present. This reduces repeated conversations, ensuring that your team is on the same page and learning from past decisions. Keep blame out of it by not recording who was on what side of any disagreement.
3. Organised to fit the team
If your work is broken into epics and stories, try to keep your documentation grouped by those same epics and stories. Using tags appropriately can help you find things again in future. If you’re using Jira and your documentation platform lets you connect with it, even better.
There’s no perfect documentation structure. If you’re a well-integrated team, it may be best to have design, development and business notes all in one place, only organised by feature. But if each discipline needs to have their own documentation, do that!
4. Flexible
Not everyone needs to follow the same format. Remember that if someone has documentation you find hard to follow or navigate, it just means they get asked more questions – but they can answer quicker. It’s better to spend time discussing the project than debating documentation structure.
Don’t be afraid to change the structure. If you need to, I recommend archiving all the old stuff, creating new documentation in the new structure, and then moving things out of the archive only when you need them. This turns moving things into an ongoing process, and doubles as documentation clean-up.
How to get started
Documentation can seem daunting, but simple habits can make life a lot easier.
1. Take your own notes
I recommend taking your own notes on everything – especially if there’s a decision being made. This doesn’t have to be part of public documentation, but it’s easier to add contemporaneous notes than to retroactively write something.
When you are figuring out what a feature does and why, even just for yourself - write it down. Something as simple as “This feature includes A because it helps users do X, it doesn’t have Y to avoid confusion,” can be game changing to a project.
2. Consistently document meetings
If you can, allocate a note-taker in meetings, workshops, or research sessions. Ideally not always the same person, so everyone can practice. If you’re working remotely, then there are AI tools that can help with this, but it’s essential to review AI outputs for errors.
You don’t need to record every one-on-one discussion you have, but if you make a decision that affects the project, then you should definitely document it.
3. Keep notes simple
Notes don’t have to be presentable. A draft is better than nothing, and you can use it to produce something more formal later on. All you really need is a reminder of who was there, what was discussed, and any actions taken.
You might do a workshop on a digital whiteboard, and just pop a link to that board into your source of truth. Writing it up properly will make it more accessible to others and give you the opportunity to improve it; but it’s ok if you don’t have the time to do that.
4. Help each other
The best reason for teams to document their work is to support each other. If someone is struggling with documenting their work, perhaps offer to chat with them. They can explain what they are doing, you can take notes and add them to the documentation. You can also record the chat so people can watch the expert explain.
You can fill gaps in documentation even outside your team. Is the platform team struggling to write documentation on how the platform infrastructure works? Write down what you understand from your previous discussions, and send it to them as a starting point. It’s a lot easier (and more fun) for them to correct your inevitable mistakes.
Prioritising good documentation
Good documentation tracks decisions, identifying where and why compromises have been made. It holds you accountable to yourself and your process. If you don’t record what you learn as you go, you risk making retroactive rationalisations instead of evidence-based decisions.
This is all about building up good habits, and that takes time. So be patient with yourself while you work on this skillset.
