By the end of this lesson you can
- Write design documents that record decisions and rationale.
- Choose the right level of documentation for the team.
- Keep documentation findable and current.
The idea
Design documentation records what was decided, why and what is still open. It complements design files, which show what but rarely why.
Common documents
- Design brief: problem, users, goals, constraints, success measures and scope.
- Design decision log: each significant decision with date, options considered, evidence and who agreed.
- Spec or handoff notes: behaviour, states, content rules and accessibility.
- Research summaries: findings and links to evidence.
- Release notes: what changed for users.
Right-sized
Write enough that someone joining in six months can understand why the product works as it does. Avoid long documents nobody reads: use headings, short paragraphs, bullet points and links to files.
Findable and current
Store documents in an agreed place (a wiki, a project folder) and link them from design files. Mark status (draft, agreed, superseded) and date them. Update or archive when decisions change.
Why it matters in real projects
Without documentation, teams repeat old debates, new members undo good decisions without knowing why they were made, and knowledge leaves when people do. Clear records save time, protect good design and make you easier to work with. They also give you strong material for portfolio case studies.
A realistic example
A new product manager joins a team and asks why checkout does not offer guest purchase. Nobody remembers, and the team is about to spend weeks adding it.
The designer finds the decision log entry: guest checkout was tested two years earlier, but because orders need age verification for alcohol, account creation was required by regulation. The log links to the legal advice and test results. The team avoids wasted work and instead simplifies account creation.
Step by step
Start a brief
Write a one-page brief at the start of each project.
Create a decision log
Use a simple table: date, decision, options, evidence, agreed by.
Log as you go
Add entries after critiques and key meetings.
Link from files
Link documents from your design file cover page.
Mark status
Label documents as draft, agreed or superseded.
Review regularly
Update or archive documents at milestones.
Common mistakes
Mistake No record of why decisions were made.
Instead Keep a decision log.
Mistake Long documents nobody reads.
Instead Keep them short and structured.
Mistake Outdated documents with no status.
Instead Date, label and update them.
Check your understanding
Choose an answer, then check it. There is an explanation either way.
Practice exercise
Exercise · about 45 min
Brief and decision log
Document a project you are working on.
Steps
- Write a one-page brief.
- Create a decision log with at least five entries.
- Link both from your design file.
- Ask a peer to explain your key decisions back to you.
Deliverable
A brief and decision log.
Self-assessment
Tick each item when it is true of your exercise. Be honest; this is for you.
4 items
Summary
- Documentation records what and why.
- Use briefs, decision logs, specs and summaries.
- Keep documents short, findable and current.
- Good records save time and protect decisions.
Further reading
Third-party sources, chosen for reliability. They open in a new tab.
- Writing a design brief (opens in a new tab)Interaction Design Foundation
Your notes
Marking complete updates your course and roadmap progress.