Half of all conflicts between clients and developers start with one sentence: “But we discussed that it would work differently.” Discussed, yes. Written down, no. A software requirements specification solves exactly this problem: it records what will be built, how it will work and what counts as done.
This guide covers the full structure of a specification with a breakdown of each section, typical mistakes with “wrong” and “right” examples, and an answer to the eternal question: who should write the spec, the client or the vendor.
What a specification is and when you really need one
A software requirements specification (SRS) is a document that describes what the system should do, not how it works inside. It answers “what are we building”, not “what are we building it from”. Architecture, the choice of frameworks and the database structure are the developers' job, not the spec's.
A good specification does three things:
When you DON'T need a spec
To be honest, not always. Here are the situations where a detailed spec is a waste of time:
MVP projects under $15K. When you're testing a hypothesis, not building an enterprise system. User stories + a Figma prototype are enough here. A 40-page spec for an MVP takes an analyst 2–3 weeks. In that time you could already build the MVP. For what an MVP and a full product cost, see our article on mobile app development cost.
Agile work with a product team. If you have a dedicated team, a product owner and two-week sprints, the backlog replaces the spec. Requirements take shape iteratively instead of being written down a year in advance.
Standard projects. An online store on an off-the-shelf platform, a landing page, a corporate website on a CMS: a brief describing the pages and content is enough.
The rule: you need a spec when the project costs $15K or more and/or takes longer than 2 months, has non-standard business logic, and the client and the developer picture the result differently. The more expensive the project, the more a misunderstanding costs.
The structure of a good spec: 14 sections
Common mistakes when writing a spec
Mistake 1: Describing a solution instead of the problem
Bad: “Put a slider with 5 banners on the home page that switch every 4 seconds with a fade-in animation.”
Good: “The home page has a block with current promotions (up to 5 at a time). The administrator manages it from the admin panel. Visitors see the promotions without scrolling.”
Why: in the first case you've imposed a specific implementation (a slider), even though the task “show promotions” might be solved better with cards, a carousel or video. Describe what you need, not how to build it.
Mistake 2: Requirements you can't measure
Bad: “The system should be fast and easy to use.”
Good: “Any page loads in no more than 2 seconds on a 10 Mbps connection. The key action (creating a booking) takes no more than 3 clicks from the home page.”
Why: “fast” and “easy” are subjective. For one person 3 seconds is fast, for another it's slow. Numbers remove the subjectivity.
Mistake 3: A 100-page spec for a $15K project
A real case: a company spent 3 months and $13K writing a spec for a $40K project. By the time the spec was ready, the business requirements had already changed. A third of the document had to be rewritten.
The rule: a spec should cost 5–10% of the project. For a $30K project, that's a spec for $1,500–3,000 (1–2 weeks of an analyst's time). For a $150K project, $7,500–15,000 (3–4 weeks).
Mistake 4: Forgetting edge cases
Bad: “The user pays for the order by card.”
Good: “The user pays for the order by card. If the payment fails, we show an error and offer to retry or choose another method. If the payment goes through but the item is out of stock, an automatic refund is issued within 24 hours with an email notification. If the user closes the page during payment, the order is held for 30 minutes.”
Why: everyone describes the main scenario. Very few describe errors and exceptions. Yet edge cases are exactly where most systems break.
Mistake 5: Not stating what's NOT included
The client expected a mobile app to come with the web platform: “well, that's obvious”. The developer assumed the scope was web only. A “Constraints and assumptions” section prevents conflicts like this.
Mistake 6: Saying one thing in one place and contradicting it in another
Section 4: “The user logs in with an email and password.” Section 9, a use case: “The user logs in with an SMS code.” When a spec is written over 3 weeks by different people, contradictions are inevitable. That's why it needs an end-to-end review before it's finalized: one person reads the whole document from start to finish and checks it for internal conflicts.
Mistake 7: Not prioritizing requirements
When a spec has 80 features and all of them are marked “required”, it's not a spec, it's a wish list. Use MoSCoW prioritization: Must have (the system makes no sense without it), Should have (important, but you can launch without it), Could have (nice to have), Won't have (not in this release). It helps fit the project into the budget: if the money only covers Must + Should, the rest goes into the next iteration.
Checklist: how to check the quality of a spec
Before you sign off on a spec and start development, go through these 10 points:
Who should write the spec?
The short answer: the vendor (the studio or developer), with the client actively involved.
The long answer: a spec translates business requirements into the language of development. The client brings business expertise (they know the processes, the pain points, the users). The vendor brings technical expertise (they know what's feasible, what's expensive and where the pitfalls are).
A spec written only by the client has business requirements with no technical thinking behind them: it's a wish list. A spec written only by the developer, without getting into the business, is a technical fantasy detached from reality.
The best process:
How much it costs to write a spec
(website, landing page, MVP)
(web platform, CRM)
(marketplace, ERP)
What's included: a series of interviews with the client, business process analysis, functional and non-functional requirements, prototypes of the key screens (Figma), an integration map, and a breakdown into stages with an estimate.
What you get: a 15–60 page document (depending on the project), a clickable prototype and a detailed development estimate.
Important: if a studio offers a “free spec”, it's most likely a 2-page brief, not a real requirements specification. A real spec takes 1–4 weeks of an analyst's work. Nobody does that for free: the cost is simply built into the development price (and you pay for it without knowing).
Our spec template
We've prepared the specification template we use on our own projects. It's not a blank placeholder from the internet. It's a working document we've refined over years of software development for dozens of clients.
What's inside:
14 sections with instructions and examples for each block. A spec review checklist: 25 points to assess how complete and solid the document is. Sample wording: how to describe functions, roles, integrations and non-functional requirements.
To get the spec template, send us a request and write “Spec template” in the message. We'll email it to you within one business day. It's free, with no strings attached.
If you already have an idea of the project but no resources to write the spec, we can take it on. We'll run the interviews, describe the requirements, build prototypes and prepare a document you can start development from right away.
FAQ
Can I start development without a spec?
You can, if the project costs under $10–15K and takes 4–6 weeks. For an MVP, user stories + a prototype are often enough. But for projects over $30K, skipping the spec is Russian roulette: you might get lucky, or it might cost you an extra 30–50% of the budget in rework.
How is a spec different from a brief?
A brief is 2–5 pages with a general description of the task: who you are, what you want, the budget, the timeline. The client fills it in within 1–2 hours. A spec is 15–60 pages describing every function, scenario, integration and constraint in detail. An analyst writes it in 1–4 weeks. The brief is the entry point to the project. The spec is the basis for the estimate and the development.
Should the spec describe the design?
Yes, but as UX requirements, not mockups. “The key action takes no more than 3 clicks”, “The interface must work on screens from 320px”, “Navigation like Notion: a sidebar + search”. Visual design is a separate stage (UI) that comes after the spec is approved.
Can the spec change during development?
It can, and it should: business requirements don't stand still. But every change has to go through a formal process: describe the change → assess its impact on the timeline and budget → get approval → update the spec. Without that process, scope creep will eat both the budget and the team's motivation.
What's the best format for a spec?
For the document, Google Docs or Notion (co-editing, comments, version history). For prototypes, Figma. For scenarios, Miro (user flow diagrams). PDF only for the final version that both sides sign. While you're working, the document should stay “alive”, open to comments and edits.
Does the spec need to follow a formal standard?
There are formal standards for requirements documents, such as IEEE 830 (last revised in 1998 and since superseded by ISO/IEC/IEEE 29148). They prescribe a rigid structure with many mandatory sections. If a government contract or tender requires a specific standard, follow it. For commercial projects, you don't need to. Today a spec has to be clear to both sides, not tick every box of a decades-old template.
How long does a spec stay valid?
In practice, 3–6 months. After that, business requirements, the market and the technology change enough that the spec needs updating. If the spec was written and development starts 8 months later, review the document before kickoff.
If you're planning a project and want to start with the right spec, get in touch. We'll run a free consultation, help you define the scope and suggest how to work together.
