How to write a project spec developers can actually quote

Most software specifications fail in one of two ways. Too vague, and development becomes a series of guesses. Too prescriptive, and you've pre-decided the implementation before anyone who understands the constraints has weighed in. Neither extreme produces good software.

A useful specification sits in the middle. It answers the questions development needs to begin, and leaves open the ones it's too early to decide. Here's what we've learned a good spec contains, and what it leaves out.

What a spec is actually for

A specification is an alignment tool, not a contract.

A specification is an alignment tool. The goal is to get everyone (business, developers, designer, tester) looking at the same problem from the same direction before work starts.

Once you understand that, the shape of a good spec becomes clearer. It should capture the problem, the users, the business context, and the constraints. It shouldn't try to capture every implementation detail, because those details will change the moment development starts asking real questions.

What a good spec contains

The four things that matter. Everything else is decoration.

1. The problem, stated clearly

Most specs jump straight to features. A good spec starts with what the business is trying to do and why. Say “our operations team spends three hours a week pulling reports manually and we want that time back” instead of “we need a dashboard that shows X, Y, and Z.”

The problem statement is what lets developers push back productively. Without it, every question becomes a negotiation about features. With it, questions become about outcomes, which is always more useful.

2. Users and their context

Who uses this system? In what setting? Under what pressures? A field technician using a phone in a rainstorm has different needs than a finance analyst at a desk. A new hire on day one has different needs than someone who's been using the tool for two years.

Good specs describe the users concretely. Job titles help. A paragraph about how they actually spend their day, what frustrates them, and what they'd consider a win helps more.

3. Constraints

Every project has constraints. Budget. Timeline. Technical environment. Compliance requirements. Existing systems that must be integrated. These set the boundaries within which creative work happens.

Naming constraints explicitly saves weeks of rework. If the system must run on existing infrastructure, say so. If the launch needs to happen before a specific event, say so. If there's a data-residency requirement, say so on page one.

4. Success criteria

How will you know the project worked? “The system is delivered on time and under budget” is not success criteria. That's project management. Real success criteria describe what changes for the business after the software ships.

Examples: “Ops team spends under 30 minutes a week on reporting.” “B2B order errors drop below 1% within three months of launch.” “New hires can process their first order within a day of starting.” These are measurable, they're tied to real outcomes, and they let you answer “was this worth it?” after launch.

What to leave out

The things that make a spec look thorough and actually make it worse.

1. Implementation decisions dressed up as requirements

“The system shall use PostgreSQL” is an implementation decision. Unless there's a genuine business reason for it (existing infrastructure, team expertise, compliance), the spec shouldn't specify it. Let the developers choose the right tools for the problem you've described.

The same logic applies to UI decisions, architectural patterns, and framework choices. If it's something the development team is qualified to decide, the spec shouldn't have decided it already.

2. Every possible edge case

Some specs try to enumerate every edge case up front. This is tempting because it feels thorough, but it's almost always a waste of effort. Most edge cases don't actually exist until the system is built. Others are far rarer than they appear in the abstract.

Better approach: name the obvious edge cases, commit to discussing others as they surface during development. This keeps the spec focused and treats development as the collaborative process it actually is.

3. Features no one has committed to building

“The system might also eventually support X” is one of the most expensive phrases in a spec. Either commit to X or leave it out. Aspirational features pull the design in multiple directions, add scope to early planning, and rarely get built in the form originally described.

If a future capability matters, design for extensibility, then scope it for later. The spec is for what you're actually building now.

How to know when a spec is ready

Four tests that tell you whether the document is actually useful.

Four tests we use.

Can a developer read it and ask useful questions? If the questions are all about clarification, the spec isn't specific enough. If there are no questions, it's probably too prescriptive.

Can a designer start sketching from it? A good spec gives enough context to design, without dictating layout.

Can QA derive test cases from it? If not, success criteria are probably buried or missing.

Would two competent teams produce similar software from it? Similar in what the software does and who it's for, though the specifics will differ. If the answer is no, the spec is underspecified in ways that matter.

If you can answer yes to all four, the spec is ready. Perfect is the enemy of shipped.

A template structure that works

How long a spec should be depends on what kind of spec you're writing.

The right page count depends on what kind of spec you're writing. The same word, “spec,” gets used for documents that serve very different purposes.

A project framing document or discovery brief runs 5 to 15 pages. This is what gets written first, before scope is finalised. It captures the problem, the users, the constraints, and the success criteria. The goal is alignment between business and development, not enumeration of every feature. If a framing document is running long, it's usually because implementation detail has crept in.

A functional specification for a real system runs 30 to 100+ pages, depending on scope. A multi-module CRM, a custom ERP, a marketplace platform, or any system with detailed feature breakdowns across multiple user roles will land somewhere in that range. The page count comes from the surface area of the system, not from over-specification. A complex CRM with eight modules genuinely needs 80+ pages of functional detail to cover what each module does, who uses it, which business rules apply, and how modules interact. Compressing it produces gaps that surface mid-build.

A technical specification, if you write one separately, runs 50 to 200 pages and covers API contracts, data models, integration logic, and infrastructure decisions. Most projects don't need this as a separate document because the development team produces it as part of the build. The exception is regulated industries, large enterprise environments, and projects with multiple development teams that need a shared technical contract.

The outline we use most often for a functional spec:

• Problem statement and business context (1 to 2 pages)

• Users and their roles (1 to 3 pages, more if there are several distinct user types)

• Success criteria (3 to 6 measurable outcomes)

• Module-by-module feature breakdown (the bulk of the document, 5 to 15 pages per module on a complex system)

• Cross-cutting concerns: permissions, audit trails, notifications, error handling (3 to 10 pages)

• Integrations: which external systems, what data flows, what happens on failure (3 to 10 pages)

• Constraints: budget, timeline, infrastructure, compliance

• Out of scope: what this project is explicitly not doing

• Open questions: decisions still pending, with a date by which each needs to be resolved

The “out of scope” and “open questions” sections are often more useful than the rest. Naming what you're not building prevents the assumptions that cause late-stage scope arguments. Listing open questions prevents the team from inventing answers to questions that should have been escalated.

Action plan: writing your spec in a week

A five-day process that produces a usable spec without needing a business analyst.

If you need to write a spec for a software project, here's a process that works. You don't need a dedicated business analyst to do this. You need a week of focused time and access to the people who'll use the system.

1. Day 1: Write the problem statement. One paragraph. What is the business trying to do, and why. If you can't write this without referring to a feature, go back and try again. The problem comes before the solution.

2. Day 2: Interview three users. Not a survey, a 45-minute conversation each. How do they spend their day? What frustrates them? What would change if this project worked? Take notes verbatim. Users' own words often end up as the clearest requirements.

3. Day 3: Draft the success criteria. Three to six measurable outcomes. “Ops team spends under 2 hours per week on X.” “B2B order errors below 1% within 3 months.” Numbers, not adjectives. These are what you'll measure after launch.

4. Day 4: List core capabilities and constraints. For a focused internal tool, 10 to 20 capabilities at a level a developer can plan around. For a multi-module system, work module by module and expect each module to need its own capability breakdown. Then the constraints: budget range, timeline, infrastructure it has to run on, regulatory requirements. Be specific about the hard boundaries.

5. Day 5: Write the "out of scope" section. This is where most specs die quietly. List everything you considered and decided not to include. Every item here is an argument you've prevented. Circulate the full spec to 2 or 3 stakeholders for a sanity check.

6. Share with a developer before finalising. Before committing to the spec as the basis for a project, share it with one experienced developer (internal or agency) for a pre-read. They'll spot the implementation-as-requirement traps, and they'll tell you which sections need more detail. A 30-minute conversation saves weeks.

7. Treat it as a living document. Version the spec. When something changes during the project, update the spec, not just the ticket. A spec that doesn't reflect the current state of the project stops being useful quickly.

By the end of the week you have a document a development team can plan from. It won't be perfect. It will be usable, which is the actual goal.

Frequently asked questions