How to Write a Software Requirements Specification: Structure, Template and Checklist

Why you need a requirements specification

A requirements specification is an agreement between the client and the development team about what exactly will be built. Without it, everyone understands the task differently: the client expects one thing, developers build another, and acceptance turns into an argument about what was meant. A good spec fixes functionality, constraints and completion criteria, so it directly affects budget and timeline: the more precise the requirements, the fewer reworks and the closer the estimate is to reality.

The question of how to write a specification should be solved before discussing price and deadlines, not after. Otherwise you get a vague estimate that grows 30-50% during the project, because both sides discovered new requirements nobody discussed at start. A good spec saves money, time and reputation. It is not just a document - it is a project management tool.

Structure of a specification: what it consists of

The structure of a specification is almost always the same; only the depth of detail changes. You can write elaborate or brief, but the order of sections is universal: context and business goal first, then users and scenarios, then technical details and data, then integrations and interface, finally acceptance criteria. This order helps the team understand not only WHAT to build but also WHY, which is critical for making right decisions.

In practice, you do not have to write every section equally deep. What matters is that each point can be verified: done or not. For example, for a simple landing the integrations section can be one line, and the interface section can be a Figma link. For a data management system, the data section may take half the document. The principle is simple: write just enough so the team understands the task and there are no misunderstandings.

Detail levels: choose by project scale

You don't always need a 50-page spec. Sometimes 5 pages covering the essentials is enough. Choosing detail level depends on project size, contract type, and team experience. The more money and time you invest, the more detailed the spec. Here's a practical guide:

Bad requirement versus good one: examples

The main mistake in a spec is vague wording that cannot be checked. At acceptance a dispute arises: client says requirement is not met, team says it is, and nobody is right because the requirement can be interpreted many ways. This is called a subjective requirement and it costs money. Here's how to spot the difference:

• Bad: the app must work fast. Good: the catalog screen opens in max 2 seconds on 3G with 500 items.
• Bad: convenient login. Good: phone login with SMS code, resend after 60 seconds, lockout after 5 failed attempts.
• Bad: the system must be secure. Good: passwords hashed (bcrypt, 12 rounds), HTTPS on all endpoints, two-factor auth for admins, all actions logged.
• Bad: beautiful design. Good: minimalist design per Material Design, colors from palette: primary #006AFF, errors #FF3B30, spacing in 8px units.
• Bad: notify user on errors. Good: if request fails, show red alert with error text and retry button, alert auto-closes in 5 seconds or can be closed manually.

The difference is that the second versions are measurable and verifiable: they make it unambiguous whether the requirement is met, leaving no room for dispute. Measurability is the main rule of a good spec. If a requirement cannot be measured - rephrase it or remove it.

Ready template: 9 sections that work in 99% of projects

Here's a skeleton you can take as a basis and fill for your task. Use it as a checklist: if you've answered all 9 points, your spec is ready for the team. Average completion time: 4 hours for simple project, 2-3 days for complex.

1. Project goal - what problem we solve, for whom, timeline. Describe business context in 3-5 sentences: who uses it now, why they suffer, why solve it now.
2. Users and roles - who will work with the system, what actions they perform. Describe each role in 1-2 sentences, clarify permissions (who can delete, who can only view, who can change).
3. User scenarios - step by step, from entry to target action, for each role. Example: manager opens app, enters password, sees list of new inquiries, clicks inquiry, enters comment, clicks send, client sees real-time notification.
4. Functional requirements - list of system features, each on separate line, no implementation details. Feature must be verifiable: not export data but export inquiries as CSV with columns: name, phone, status, creation date, outgoing emails.
5. Non-functional requirements - expected load (users/items per day), speed (page load time), security (encryption, 2FA), platforms (mobile browser, iOS, Android), interface language, accessibility requirements.
6. Integrations - payments (which system, which methods), notifications (SMS, email, push, Telegram), maps, analytics, external APIs. Describe when integration triggers and what should happen.
7. Data - what we store (inquiries, users, logs), retention periods, data protection requirements (GDPR if EU users), backup policy, encryption at rest and in transit.
8. Interface - mockups (Figma or Penpot link), tone (formal/friendly), branding (colors, logo, fonts), mobile adaptation, accessibility (contrast no worse than 4.5:1, font size > 14px).
9. Stages and acceptance - how we split work (MVP, second release), timeline for each, acceptance criteria (all features work, tests written, documentation done, no critical bugs).

Even brief completion of this template (1-2 paragraphs per section) removes most future questions. The team can start development based on your answers, and you'll know exactly what will be built and when.

Common spec mistakes and how to avoid them

Even experienced clients make spec mistakes. Usually not fatal, but they cause rework and disputes that consume 10-20% of budget. Here are the most common:

• Writing how to build it instead of what the result should be. For example, use React instead of interface responds in 1 second. Choosing technologies is the team's job; your job is the result and constraints. Exception: if you have a strict requirement (e.g., legacy integration), mark it clearly.
• Mixing mandatory and nice-to-have. Clearly mark what is needed for launch (MVP) and what can wait for version 2. Otherwise the team assumes everything, estimate grows, timeline slips, you get a plane instead of a car.
• Forgetting non-functional requirements. If you don't state load and data requirements, the team assumes minimum - reworking for growth costs 2-3x more than building right from start.
• Not describing edge cases. What happens if user loses internet mid-operation? If payment fails but money was charged? If list is empty? Unhandled scenarios are exactly what surface at acceptance most often.
• Vague acceptance criteria. Don't write when everything is ready. Write specifically: all 12 features work without errors, >= 70% test coverage, code on dev server, documentation ready, no critical or major bugs.
• Not attaching mockups or design system. If you have mockups in Figma - attach with note on which screens are MVP. If no design - describe clearly: RGB colors, fonts, spacing, branding, contrast.
• Forgetting regulation. If working with data in Russia - clarify data protection. If payments - check standards (PCI DSS). If EU clients - GDPR. Not just requirements - these are architecture constraints affecting cost and timeline.

Readiness checklist: is your spec ready to start development

Before sending the spec to the team, check these questions. If you don't answer yes to most, the spec needs more work. Each skipped point is a $1k-5k rework risk.

• Is the project goal clear in one sentence and why it needs to be done now?
• Is every requirement measurable and verifiable (or is it subjective like beautiful)?
• Are MVP and nice-to-have requirements marked clearly?
• Are edge cases described (empty list, payment failure, lost connection, user blocked)?
• Is expected load stated (users per month, items per day, requests per second)?
• Are security and regulation requirements described (data protection, GDPR, payment standards)?
• Are mockups attached (Figma, Penpot) or is design precisely described (colors, fonts, spacing)?
• Are timeline and work stages stated with acceptance criteria for each?
• Are requirements tied to roles and scenarios (who uses what)?
• Is there a complete list of all integrations (payments, notifications, APIs, export)?
• Are acceptance criteria clear for each stage (test coverage, documentation, bugs)?
• Do you understand what can be reused (SaaS, library) versus built from scratch?

What to attach to your spec beyond text

A spec is not just words. Attach supporting materials to help the team understand faster:

• Interface mockups (Figma, Penpot, even tablet/phone photos) - logic is clearer from pictures than words. Mark which screens are MVP.
• Data flow diagrams (where data comes from, where it goes, where processed) - especially important for systems with integrations and complex logic.
• Permission matrix by roles (who can read/write/delete in each section) - prevents access control bugs.
• Example API responses or format of stored data - if integrating external service, attach real JSON examples.
• Logging and analytics requirements: which events to log, in what format, what detail level.
• Screenshots of competitors or similar solutions (if you have them) - help team understand your vision and avoid others' mistakes.
• Links to regulation or compliance docs if relevant (data protection laws, payment standards) - team understands constraints and can plan architecture.

What to do if you have no spec but need development now

If you have an idea but neither a spec nor clear understanding of scope - that's normal. You should not write a detailed document right away. The answer is a discovery phase (analysis).

Discovery is when the analyst works with you to turn the idea into a prototype, requirements backlog and grounded estimate. The analyst asks questions, draws diagrams, suggests options you didn't consider. The output is a spec - but one tested for realism rather than written blind. It is worth the cost.

Discovery usually takes 2-4 weeks and costs 10-20% of development budget (roughly $500-1500 for typical project). It is an investment that pays back immediately: a correct spec eliminates half the rework. If you're choosing a contractor, notice if they're ready to start with analysis rather than immediately quoting app development without a document. A contractor willing to do discovery is usually higher quality.

How spec quality affects development cost and timeline

Spec quality directly affects estimate honesty and scope creep. Here's how it works: vague spec means the team adds a risk buffer to estimate. Instead of 100 hours they write 150, because something unexpected might surface. Price ends up 30-50% higher than needed. Detailed spec means the team estimates precisely. They know exactly what to do, can break into tasks and estimate each. Price is more accurate, often lower.

Same with timeline: vague spec equals uncertainty, which means a buffer in the plan. Precise spec means plan without buffer, which means realistic timeline you can trust. Also, detailed specs enable fixed-price work. Without one, the honest model is Time & Material, because nobody can guarantee the scope. Time and materials is a risk for the client.