How to write a specification for an IT project

A real case first: a founder held two quotes for the same mobile app, $18,000 and $47,000. Once a specification existed, the cheaper vendor turned out to have scoped no offline mode, no role management and no admin back-office, about 60% of the product by effort. The expensive quote was not expensive; the cheap one was quoting something else. A specification is what makes that visible.

In short: a useful specification describes what you need to achieve and how everyone will know it worked — not the technical solution, which your vendor is better placed than you to propose. It often runs to ten or twenty pages. A hundred-page document that specifies screens but defines no acceptance criteria protects you less than a single page that defines them.

The seven-part structure

1. Context and problem — what doesn't work today, with a number if you have one: hours lost, orders mislaid, data re-keyed.
2. Measurable objectives — what must be different afterwards. "Cut the time from order to production launch from two days to two hours" is an objective. "Improve productivity" is not.
3. Functional scope — the processes covered, and explicitly the ones that are not. The exclusion list prevents more disputes than the inclusion list.
4. Constraints — existing systems to integrate with, legal obligations, availability requirements, languages.
5. Data — what must be migrated, from which sources, and who is responsible for cleaning it. This section prevents the single most common end-of-project argument.
6. Acceptance criteria — the checks that must pass for a deliverable to be accepted. Written before development, not after.
7. Governance — who decides, how often you meet, and how quickly the vendor's questions get answered.

The three classic traps

Specifying the solution instead of the need

"A blue button top-right that exports to Excel" closes the door on a better answer. "The manager must be able to take the filtered list away and work on it offline" leaves it open. Describe the intent; let the vendor propose the solution, then judge it.

Leaving out acceptance criteria

Without criteria written up front, acceptance becomes a negotiation of opinion at the end of the project — exactly when you have the least leverage. It is the most valuable part of the document and the most frequently missing.

Confusing exhaustiveness with precision

A long specification dilutes the important parts. If everything is a priority, nothing is: classify explicitly into "must have", "should have", "later".

The test to run before you send it

Give the document to someone who doesn't know your business and ask two questions: what has to be built? and how will we know it worked? If they can't answer the second, the document isn't ready — and no vendor will be able to quote it seriously.

A requirement written three ways

Here is the same requirement for an order-management tool, rewritten until it can be tested.

1. Vague: "The system should handle orders efficiently."
2. Better: "A sales rep can create an order and send it to production."
3. Testable: "A sales rep can create an order with up to 50 line items in under two minutes; the production team sees it in their queue within 60 seconds; an order missing a delivery date cannot be sent."

Only the third version can be accepted or rejected without an argument. That is what the standards call a verifiable requirement; ISO/IEC/IEEE 29148 lists it alongside "necessary", "unambiguous" and "feasible" as the qualities of a good requirement.

Non-functional requirements people forget

Functional requirements say what the product does. These say how well, and they are where most surprises hide. ISO/IEC 25010 groups them into performance, security, reliability, usability and maintainability. For a typical business application, write down at least:

• Performance: acceptable page-load time at your expected number of simultaneous users.
• Availability: what downtime is tolerable, and when (a payroll tool at month end is not the same as an internal wiki).
• Security: who can see what, and what must be logged. For a ready list of verifiable security requirements, the OWASP Application Security Verification Standard is a good starting point.
• Data: retention, export, and what happens to records when a user leaves.
• Languages and locale, if you operate in more than one.

The role question that doubles the scope

In the two-quotes case above, the cheaper vendor had scoped no role management and no admin back-office. Ask early: how many kinds of user are there, and what may each do? A platform I built for federations has five roles per organisation, and each role is, in effect, its own set of screens and rules. Roles are not a detail; they are a multiplier on scope.

A one-page checklist before you send the spec out

• Every must-have has acceptance criteria a non-developer can run.
• An out-of-scope list exists and is not empty.
• The data section says who migrates and cleans existing records.
• Roles and permissions are listed.
• Non-functional requirements have numbers.
• Someone outside the project has read it and answered "what will be built, and how will we know it worked?"

Where to go from here

For a ready structure and a worked example, read the PRD template for an MVP. If you would rather have it written with you, the Technical Specification & PRD offer delivers ranked requirements, a data model, acceptance criteria and a build estimate in ten working days. I do not bid on the build, so the document stays neutral.