The Solution Document is not paperwork. It's the compression algorithm for everything a team knows about a project. Done well, it replaces five status meetings and twenty Slack threads. Done badly, it's a tomb.
The trick is that it evolves. The first draft, at Solution Approval, is deliberately thin. A good Solution Document at stage 2 is one page. By Shaping Review it's specific enough to estimate. By Launch, it has acceptance criteria and a risk log that's been updated every week.
A Solution Document that hasn't changed in a month is either finished or abandoned. Usually abandoned.
The header block
Every Solution Document opens with this metadata card. It's the first thing a reader sees and the most frequently outdated. Keep it current, or stop calling it current.
The thirteen sections
Not every project needs every section filled in depth. But every section needs a conscious decision. "we're not including this, because…"
1 · Opportunity statement
What is the idea, request, feedback, requirement, contract clause, or compliance restriction? Describe it in plain language. If it came from a user, quote them.
2 · Objectives
What do we actually want to solve? Strip away the implementation. "We want to reduce the time it takes to onboard a new customer from days to hours" is an objective. "Build a wizard" is not.
3 · As-is
The current state. How are users dealing with this today? What workarounds exist? A UX flow diagram earns its place here, showing the current pain is how you sell the future state.
4 · Value
The honest answer to "why should we do this?" Back it with the scoring matrix. Business scorecard for product work; technical project matrix for architecture.
Pro tip If the value section is longer than the objectives, the project is probably a solution looking for a problem. Cut.
5 · Cost
Estimated cost in developer days. This is a range until Shaping is done. Never express it as a single number before you've earned it.
6 · Milestones
Breakdown into phases with baseline and revised completion dates. Keep the old dates visible, strikethrough them rather than delete. The history of slippage is itself a diagnostic.
| What | Planned | Actual / Revised |
|---|---|---|
| Shaping complete | Apr 22 | |
| Dev start | Apr 28 | |
| UAT start | Jun 10 | |
| Release | Jul 31 |
7 · Suggested solution
This is the section that grows with the project. Three maturity levels:
- Business Case stage, a short description of each proposed option
- Shaping stage, enough detail to estimate effort
- Post-Shaping stage, the clear, committed solution with wireframes and process diagrams
8 · Risks & assumptions
List them. Don't hide them. Risks that are written down get mitigated; risks that are whispered get ignored until they materialise.
9 · Acceptance criteria
Bullet points. What, concretely, has to happen for this to be "done"? This is the bridge to grooming stories.
10 · Out of scope
Write this section before kickoff, not after. "We're not doing X" is the cheapest feature you'll ever ship.
11 · Required deliverables
Any expected outputs beyond the product itself, reports, compliance artefacts, training materials.
12 · Resources
Documentation, research, standards. Anything a new team member would need to understand context. Include external links like OWASP Top Ten where relevant.
13 · Risk log
A plain, ugly table. Updated in every stakeholder meeting. The discipline is writing risks down, the template is almost irrelevant.
| ID | Risk | Impact | Likelihood | Owner | Mitigation | Status |
|---|---|---|---|---|---|---|
| R1 | Tech dept blocks infrastructure access for new platform | High | Medium | @Victor Spinei | Weekly 1:1 with tech dept lead; escalate to sponsor if unresolved > 2 weeks | Active |
| R2 | Vendor deliverable D3 slipping vs SOW | Medium | High | @Victor Spinei | Escalation call scheduled; written acceptance criteria clarified | Active |
| R3 | Legacy system users resist new data platform | Medium | Medium | Change lead | Pilot with one team first; reuse existing database where possible | Monitoring |
How the document evolves
A single Solution Document passes through three distinct versions of itself. Writing as if it should be polished at stage 2 is the most common mistake I see.
Rules of the Solution Document
- One owner, one document. If two people are editing, one is the owner and the other is proposing changes.
- Write the out-of-scope section first. Constraint is the friend of delivery.
- Update the status block weekly. If the header is stale, readers stop trusting the body.
- Record decisions, not discussions. The document is the decision log, not the meeting minutes.
- Retire it at validation. When validation is done, freeze the document. Don't let it linger as a zombie.
Remember The Solution Document's job is to make the thinking visible. When in doubt, write the sentence that's hardest for you to defend. That's the one your team needs to read.
What to read next
The Value section of this document leans on the scorecard matrix. If you haven't seen it yet, start there.