How to Write a Software Requirements Spec

Why a spec matters

A spec is the agreement about what will be built. Without one, every supplier guesses, quotes vary wildly and arguments start at the end of the project about what was "obviously included". With one, you can compare quotes properly, agree a fixed price and test the finished system against something written down.

It does not need to be a hundred pages. For most business systems, ten to fifteen pages of clear writing, sample data and rough sketches is plenty.

What to include: a simple template

1. Background and goal. What is wrong today and what will be better. For example: "Orders from the website are retyped into Sage, taking two hours a day and causing errors."
2. Users and roles. Who will use it (office staff, managers, customers, suppliers, engineers) and what each should and should not see.
3. User stories. "As a warehouse manager, I want to see today's orders grouped by courier, so I can book collections." One line each, grouped by area.
4. Business rules. Pricing, discounts, VAT treatment, approvals, cut-off times, numbering formats. These hide most of the complexity.
5. Data. What you store, where it comes from now (spreadsheets, Access, another system) and how much of it there is.
6. Integrations. Name every system: Xero, QuickBooks Online, Sage, Shopify, Stripe, Microsoft 365, a courier, HMRC. Say which direction data flows and how often.
7. Reports and outputs. Invoices, PDFs, exports, dashboards, emails.
8. Non-functional needs. Number of users, uptime expectations, accessibility, where data must be hosted, GDPR, backups, audit trails.
9. Priorities. Mark each item must, should or could have (the MoSCoW method), so a first phase can be agreed.
10. Constraints. Deadlines that genuinely cannot move, budget range, technology you already use.

Mistakes that make specs less useful

• Describing the solution, not the need. "A dropdown with 40 options" is less helpful than "staff must pick the job type quickly".
• Leaving out the exceptions. The normal order takes a minute to explain. The credit-on-account customer with a split delivery is where the cost sits.
• Copying a competitor's product. Features you do not need still cost money to build and maintain.
• No sample data. Real (anonymised) invoices, spreadsheets and exports show the edge cases faster than any description.
• Writing it alone. The people who do the job daily know the workarounds. Ask them.

From spec to fixed-price quote

A spec written by the business is the starting point. A developer then turns it into technical decisions: the data model, the integration approach (for example OAuth 2.0 with the Xero API and webhooks for updates), the hosting and what will be tested. That is what a discovery and scoping stage does. The output is a document both sides sign off, with screens, data and a price.

If a quote comes back with lots of assumptions, that is a sign the spec has gaps. Answer them in writing and ask for the quote to be updated.

An example, written well

Here is a short extract from a spec for a field service business, showing the level of detail that helps a developer quote accurately:

Goal: Engineers currently write job sheets on paper. The office types them into a spreadsheet and then raises invoices in Xero. This takes around a day a week and jobs are sometimes not billed. We want job sheets completed on a phone and invoices raised automatically.

Users: 12 engineers (phone, often poor signal), 3 office staff (desktop), 1 manager (reports only).

User stories (must have):

• As an engineer, I see today's jobs in order, with address, contact and notes.
• As an engineer, I record time on site, parts used from a list, photos and a customer signature, even without signal, and it sends when I reconnect.
• As office staff, I review completed jobs and approve them for invoicing.
• As office staff, approved jobs become draft invoices in Xero with the right account codes and VAT.

Business rules: Call-out charge applies to the first hour only. Contract customers are not charged call-out. Parts are priced at list price unless the customer has a discount band (A, B or C).

Data: around 900 customers and 400 parts in the current spreadsheet (sample attached).

Could have: customer portal to view past jobs.

Notice that it describes the problem, the people, the rules and the volume, and it attaches real data. It does not dictate screens or technology, which leaves room for the developer to suggest the best approach.

When to talk to dijitul

You do not need a finished spec to talk to us. Many clients arrive with a page of notes and a spreadsheet. dijitul starts with a free chat, asks the questions that fill the gaps, then writes up the scope and gives a fixed-price quote. If the system is large, we split it into phases so you can start with the part that saves the most time. Send us what you have, however rough.

Related