"The dashboard should show relevant metrics" is a spec. It's also meaningless. Which metrics? Relevant to whom? Over what time period? Updated how often? What does the UI look like when there's no data?
A useful spec answers one question: if you handed this to a developer you'd never met, would they build the same thing you're picturing?
User stories with acceptance criteria
The format that works is user stories paired with acceptance criteria. A user story tells you who does what and why. The acceptance criteria tell you how you know it's done.
User story: "As an ops manager, I want to see a weekly summary of ticket resolution times so I can identify where we're falling behind."
Acceptance criteria for that story might look like:
- The page shows average, median, and 90th-percentile resolution time for the last 7 days
- Data is broken down by team
- The page reflects data as of the last full day, updated each midnight
- If there are no tickets in the period, the chart shows a zero value rather than a gap
That last one matters. Edge cases in acceptance criteria are where most implementation bugs start. If the spec doesn't describe the empty state, the developer will invent something. It might not be what you wanted.
A rough data model
You don't need a full entity-relationship diagram. A rough sketch of the main entities and their relationships saves hours of back-and-forth during implementation. "Users have many projects, projects have many tasks, tasks have an assignee and a due date" tells the developer enough to start modeling without leaving the shape of the data up to them.
Data modeling decisions made during implementation are hard to undo later. Decisions made during discovery are cheap to change.
What's explicitly not in scope
If the dashboard will not include CSV export in this phase, write that down. If mobile is out of scope, say so. If the admin panel is a later phase, list it as out of scope now.
This feels unnecessary when the project is fresh and everyone is aligned. It becomes essential three weeks in when someone assumes you're building something you agreed not to build. The spec becomes the reference for those conversations. Without it, you're arguing from memory.
Known unknowns
Things you haven't figured out yet that could affect the timeline or design. A dependency on a third-party API you haven't reviewed in detail. A data migration whose size or complexity is unclear. An integration with a legacy system you haven't accessed yet.
Naming these upfront means nobody is surprised when they need to be resolved. A known unknown is something you can plan around. An unknown unknown is what causes weeks to disappear in the middle of a project without anyone understanding why.
Length
A spec doesn't need to be long. It needs to be precise. Two pages that answer the questions above are more useful than twenty pages of vague requirements. Long specs usually mean the author hasn't thought it through yet. Short, specific specs usually mean they have.