If you want to know how to write a spec developers can quote, the answer is one plain document. It says what problem the software solves, who will use it, which features the first version must have, what is left out, and how you will know each part works. Send that same document to every developer you ask, and their prices will describe the same thing. If you need help writing or testing a brief, software consulting is the place to start. Treevoxa is a remote team and agrees overlap hours with each client, so you can set working times that suit your business in Canada or the United States.
The rest of this guide covers each part of the spec, how long it should be, and how to check the quotes that come back against it.
1How to write a spec developers can quote: the six parts
A spec for developers has six parts. Cover them in this order, and a developer has what they need to price the work:
- The business problem and goal
- Features, written as behaviour
- What the first version will not do
- Must-have and nice-to-have items
- Non-functional needs, in plain words
- Assumptions and open questions
Each part has its own section below.
Start with the business problem and goal
Write one short paragraph on what happens now. Name the people involved, the task they are trying to finish and the point where the process breaks.
For example: orders arrive by email, someone retypes them into a spreadsheet, and the warehouse hears about them a day later. That is the problem. Then add one line on what success looks like in plain terms, such as fewer orders typed twice. Leave out targets and figures unless you have them.
Write features as behaviour, not wishes
Describe what a user does and what the system does in response.
Compare two versions. A wish says: make leave requests easy to use. A behaviour says: the manager approves a leave request from a phone, and the record is saved with a time stamp. A developer can price the second. They can only guess at the first.
Keep each feature to one or two sentences. If you cannot describe the behaviour, you have not decided what you want yet, and a quote will hide that gap as a guess.
Say what the first version will not do
A clear out-of-scope list stops a quote being low on paper and high in change requests. Developers price what is written. Anything left unwritten gets a margin or turns into a change request later.
Name what is excluded for this version. Owners often leave out reporting, links to other systems such as accounting or a payment provider, and moving old data in from spreadsheets or an old system. If you want those later, say so and mark them as a later phase. That is a decision, not an oversight.
Mark each item as must-have or nice-to-have
A must-have is something the software cannot launch without. A nice-to-have is something you want if it does not delay launch or add much cost.
Developers can quote must-haves firmly when they are marked, and they can price the nice-to-haves separately. Keep the must-have list short enough that you can read it in one sitting. If it runs to pages, you have not yet decided what matters most.
List non-functional needs in plain words
These are the rules that sit around the features. Cover four things in ordinary language:
- Who can see what. For example, only the branch manager sees payroll totals.
- How quickly pages should respond. Describe it in terms staff would notice, such as no waiting at the till.
- How often the system must be available. For example, during trading hours.
- What happens if it goes down. For example, staff take orders on paper and enter them later.
Keep it to what your business actually needs. Do not write security certifications or compliance claims into the brief unless someone has checked that they apply.
Record assumptions and open questions
List what you assume and what you do not yet know. For example: we assume the existing barcode scanners will work with the new system, and we do not know whether the accounting package has an interface we can use.
Ask every vendor to state their own assumptions back to you in writing. A quote that hides its assumptions is hard to compare, because you cannot tell whether two vendors are pricing the same starting point.
2How long should a software requirements document be?
Length follows the size and risk of the project. There is no correct page count.
A short brief can be a fair start for a simple tool if it covers the six parts above. A multi-module ERP, with stock, accounts and staff records all linked, needs more pages, because more people have to agree on more rules. For that kind of work, see ERP software development. For a checklist to test your draft against, read the ERP requirements checklist for small business. Many templates and guides come from firms that sell development work, so treat any page count they give as their view, not a rule.
Use a simpler check. Would two developers read your brief and price the same thing? If each would ask the same three questions before quoting, those questions are the gaps to fill. If one quote sits far above the others, look at the brief before you blame the developer.
3How do I write acceptance criteria?
Each must-have needs a test with a clear pass or fail. Acceptance criteria are those tests. You check them at handover, and they tell the developer when the work is finished.
Words such as fast, easy and reliable cannot be tested, so nobody can accept or reject them. Here is one plain example from a point-of-sale brief, written as an illustration:
After a sale is saved, the stock count drops by the quantity sold, and the receipt shows the same total.
Anyone can check that. Either the stock count drops or it does not. Write one or two tests for each must-have. If a feature has no test you can run, either the feature is not clear enough yet or you do not know what you want from it.
4Should I pay for a discovery phase?
A quote prices a brief. Discovery tests the brief. A discovery phase is paid early work to find out what the project really involves, so the scope is firm before anyone commits to a build.
It makes sense when you have a rough idea and little detail, when the process is new to you, or when several parts of the business will be affected and nobody has mapped them. It is less useful when you already know the process, have the rules written down and want to start building.
Ask any vendor three things in writing:
- What discovery covers, week by week.
- What it costs.
- What happens to that work if the build goes ahead.
A good answer says the discovery output becomes the spec the build is priced against. A weak answer is vague, or it charges again for work already done.
For how Treevoxa prices its work, see the software development rates page. The software development cost calculator can help you think about the size of a project before you ask for quotes.
5Should I build or buy the software first?
A spec for a ready-made product is a different document from one for custom work. If a product already does most of what you need, your spec becomes a list of gaps and the settings you need. If it does not, the spec has to describe your process in full.
Answer these four questions first:
- Is the process unique to your business, or is it the same as most firms in your trade?
- Does a ready-made product already cover most of your must-haves?
- Who will maintain the software and change it when the business changes?
- How many people will use it, and how much will the work change over the next few years?
If the process is common and a product covers most needs, buy. If the process is what sets you apart, build. For a fuller set of questions, see the build vs buy software decision checklist. If a ready-made system with full source code fits, see ready-made software with source code.
6What should I have ready before asking for quotes?
Have five things ready before you send anything out:
- The current version of the spec, with a version number and a date.
- Your answer to build or buy, with the reason.
- One named person who makes decisions and can answer questions quickly.
- The same brief for every vendor, so the quotes can be compared.
- Sample files with no real personal data in them.
Also put the answers you need into the brief itself: assumptions, exclusions, the rate for change requests, payment terms and the launch date. If the brief asks for them, no vendor can skip them.
7How do I compare software proposals fairly?
Send the same version of the brief to every vendor. Then compare each quote against the brief, not only against the other quotes. Use this table as your checklist.
| Check | What good looks like | Red flag |
|---|---|---|
| Scope match to must-haves | Every must-have appears by name, with its own line or phase | A must-have is missing, or the quote says "standard features" without listing them |
| Stated assumptions | The vendor restates your assumptions and adds its own, in writing | No assumptions listed, or they are buried in the small print |
| Stated exclusions | Each out-of-scope item is named, and marked as later or extra | Exclusions are not mentioned, so the gaps turn into change requests |
| Rate for change requests | A stated rate for changes, and a way to price a change before work starts | No rate given, or "we will discuss it when it comes up" |
| Payment terms | Clear milestones, with what each payment covers | A large payment up front with no link to delivery |
| Launch date | A date tied to the written scope | No date, or a date that moves every time scope is raised |
Treevoxa works to written scope, fixed price and launch date before work starts. Hold every vendor to that standard, Treevoxa included.
A vague brief pushes vendors in two directions. Some add a risk margin to cover what they cannot see, so the quote looks high. Others quote low, win the work and recover the difference later through change requests. Both come from the brief, not from the developers. A sound brief makes the quotes comparable, and the lowest quote is not always the best one.
If you run a business in Canada or the United States, ask each vendor which working hours they will cover. Treevoxa agrees overlap hours with each client, so the answer should appear in the quote itself, not in a conversation you may not remember.
8Can I write a spec if I am not technical?
Yes. Write the problem, the users and the results in business terms. Say what you know and what you do not. The developers or a consultant fill in the technical how.
Most owners who write a good brief are not technical. They know their work well and can say exactly where it goes wrong. That knowledge is what developers need most.
Do not guess at technology choices in the brief, such as which database or programming language to use, unless you have a real reason. A wrong guess can add cost or limit what the vendor can offer. If a vendor insists on a tool you did not ask for, ask why, and ask what it changes for you. If you want a second pair of eyes on a draft, you can contact Treevoxa.
9What should the spec say about personal data?
List the personal and health-related information the software will hold, and answer these questions in the spec:
- What data will the software hold? For example, customer names, contact details, dates of birth or health records.
- Who can see each type of data?
- Where will it be kept, and who runs the servers?
- How long will it be kept, and how will it be removed?
This guide does not cover Canadian or US privacy or health-data rules. Before you share any data with a vendor, confirm your obligations with a qualified adviser in your own province or state. Also remove real personal data from any sample files you send out for quotes. Use made-up records with the same layout instead.
10Who should own the source code and accounts?
Make ownership a spec item, not an afterthought. The spec should say who owns each of these:
- the source code
- the code repositories
- the cloud accounts
- the domain names
- the logins for third-party services, such as email, payments and maps
Treevoxa's position is that you own the code and accounts. Ask any vendor to confirm that in writing before you sign, and check that the spec names who holds each item. If a vendor hesitates on this, treat it as a serious issue, not a detail to settle later.
11Who should sign off the software spec?
One named owner signs it off, along with the people who run the process every day. The owner holds the budget and makes the final call. The daily users confirm that the features match how the work really happens. Without the second group, the spec describes how managers think the work is done.
Treat sign-off as a dated, numbered version. For example, Version 1.2, dated, with the approvers' names listed beneath it. Any change after sign-off goes through a written change request with its own price and date. An informal message in a chat app is not a change request. If a change is agreed in a meeting, write it down that day and add it to the log.
12How do I keep the spec up to date?
Treat the spec as a living document. Give it a version number and a date. Log each decision and each scope change, with a short reason. When something changes, update the version and share the current one with every vendor still quoting, so the comparisons stay fair. A vendor who quoted against version 1 should not be compared with one who saw version 2.
Once the build starts, the spec is also your test of what you receive. Keep the acceptance criteria in it, and check the finished work against them at handover.
To sum up, knowing how to write a spec developers can quote means writing the problem, the features and the exclusions in plain words, and testing each must-have. Settle ownership and change requests in writing before you sign. Then send the same dated version to every developer you ask.