How to Write Software Requirements a Developer Can Use

What a developer actually needs from you

A developer needs four things: who will use the software, what job each user is trying to finish, what systems it must talk to, and how you will judge that it works. That is the whole list. Screen layouts, colour choices and technology stacks are the builder's job — modern component libraries make good interfaces cheap, and a competent team will pick the stack that fits the problem.

What a developer does not need is a solution written as if it were a requirement. 'We need a React app with a Postgres database' tells us nothing about your business and locks the build into choices made without evidence. 'Our three sales staff each waste an hour a day retyping enquiries from email into a spreadsheet' tells us almost everything, and probably costs less to fix than you expect.

The one-page skeleton you can copy

Copy the headings below into a blank document and answer each in plain sentences. If a section takes you more than three or four sentences, you are probably describing a solution rather than a need — step back up a level. A completed version of this skeleton is enough for any serious team to produce a written fixed quote.

• THE PROBLEM — two sentences on what hurts today and what it costs you (hours, missed sales, errors).
• USERS — each type of person who touches the system, and roughly how many of each (e.g. 2 admins, 10 staff, ~300 customers/month).
• CORE WORKFLOW — the single most important journey, step by step, from trigger to finished outcome.
• MUST INTEGRATE WITH — every external system involved: Stripe, HubSpot, WhatsApp Business API, Google Calendar, your accounting tool.
• DATA — what must be stored, what already exists (spreadsheets, an old system), and whether it needs migrating.
• OUT OF SCOPE FOR V1 — features you want eventually but will live without at launch.
• DONE MEANS — three to five testable sentences describing behaviour you can verify on launch day.
• CONSTRAINTS — deadline, budget band, and anything non-negotiable (existing domain, existing customer accounts, compliance needs).

Write workflows, not feature lists

A feature list says 'booking system, admin panel, notifications'. A workflow says: 'A customer picks a service, sees available slots, pays a deposit, and gets a WhatsApp confirmation. Staff see the day's bookings each morning. If a customer cancels more than 24 hours ahead, the deposit refunds automatically; inside 24 hours it does not.' The second version is barely longer, and it just answered a dozen questions the first version left open.

Workflows expose the decisions that actually shape cost: refund rules, edge cases, who approves what. Every decision you make in the document is one the developer does not have to guess at, pad the quote for, or interrupt you about in week two. If you cannot describe the workflow, that is useful information too — it usually means the process needs designing before it needs automating.

Acceptance criteria: how you will know it is done

The 'done means' section is the most valuable page real estate in the document, because it becomes your launch-day test script and the objective standard both sides sign up to. Write each criterion as a sentence a non-technical person could verify by sitting at the product and trying it.

Good criteria are binary — they pass or they fail. 'The dashboard should be fast' is not testable. 'The dashboard loads current-month figures in under three seconds on an ordinary phone connection' is. Aim for three to five of these; if you need twenty, your version one is too big.

• A new customer can register, book and pay without any help from staff.
• An admin can refund a booking and the customer receives an email within a minute.
• Enquiries from the website contact form appear in HubSpot within five minutes.
• The system sends a reminder 24 hours before each appointment via WhatsApp.

What to leave out of version one

The out-of-scope section is where budgets are saved. Multi-language support, native mobile apps, advanced analytics, role hierarchies beyond admin-and-user, and integrations with systems you have not bought yet — all of these are common version-two features masquerading as launch requirements. Cutting them rarely hurts the launch and often halves the price.

A useful test: for each feature, ask what happens in the first month if it is missing. If the answer is 'someone does it manually for ten minutes a day', defer it. Manual workarounds are cheap experiments that tell you whether the automated version is worth building at all. At PINCLER this is how larger ideas fit fixed phases of $2,500 or less — each phase ships something usable, and the out-of-scope list becomes the menu for the next one.

Common mistakes that inflate quotes

The same handful of briefing mistakes appear over and over, and each one either raises the quote or plants a mid-project dispute. They are all avoidable in an afternoon.

• Prescribing the technology instead of describing the problem — you pay for choices made without evidence.
• Listing every user type as equally important — pick the one whose workflow must be excellent; the rest can be plain.
• Leaving data migration unmentioned — moving years of spreadsheet history is often more work than the app itself.
• Using 'etc.' and 'and so on' in scope lists — a quote cannot price an et cetera, so it prices the worst case.
• Skipping the out-of-scope section — everything unsaid becomes an argument later.
• Describing screens instead of outcomes — layouts are cheap to change; misunderstood outcomes are not.

What poor requirements cost, in published numbers

The research on this is unusually consistent. PMI's Pulse of the Profession research has reported that inaccurate requirements management is a factor in 47% of unsuccessful projects, and an earlier edition of the same survey found 37% of organisations naming inaccurate requirements as their primary cause of project failure. Those studies describe large organisations, but the mechanism scales down perfectly: the requirement that was never written down becomes the feature that was never built, argued about at handover, or paid for twice.

The wider numbers are no kinder. The Standish Group's CHAOS research has reported that only around 31% of software projects succeed outright, with roughly half 'challenged' — late, over budget, or delivering less than planned — and 19% failing entirely. A McKinsey study with the University of Oxford covering more than 5,400 IT projects found large projects running 45% over budget on average while delivering 56% less value than predicted. Requirements are not the only cause behind those figures, but they are the one input you control completely, for free, before anyone bills an hour.

The same relationship shows up at small scale in our own delivery data. Across PINCLER's 79 documented projects — every one quoted from a one-page-style brief and fixed between $500 and $2,500 — the median build is $1,450 and ships in a median of 13 days; the full dataset is published at /research/what-you-can-build. Clear scope is why those numbers stay flat. A project that starts with an honest page rarely discovers itself mid-build.

A worked example: the same project, briefed two ways

Take a booking system for a small clinic and price it under two briefs. Brief one says 'we need a booking system with payments and reminders'. A team estimating that must cover the unknowns: staff rosters or not, deposits or full payment, refund rules, group sessions, existing patient records. A cautious estimate spans 120 to 220 hours, and any sensible hourly quote protects the top end. At $50 per hour — inside the range published directories report for many offshore teams — that is 220 × $50 = $11,000, or an open-ended hourly arrangement that averages out the same way.

Brief two is the one-page version: one service type, deposits via Stripe, refunds automatic outside 24 hours, WhatsApp reminders, staff see a daily list, no rosters in version one. The unknowns are gone, so the price can be fixed against real scope; on our fixed-price model that lands in the $1,000–$1,800 band with delivery in roughly two weeks. The difference between the two quotes is not the developer's typing speed — it is your page. The ambiguity was costing roughly $9,000 before anyone wrote a line of code.

What a clear brief buys, by project type

One-page requirements are also the reason fixed prices can be published at all. The table below shows median fixed prices and delivery times across PINCLER's 79 documented projects by category; every project in the dataset shipped from a brief no longer than the skeleton above. Use it to sanity-check your own scope — if your 'simple website' brief is drifting towards web-app pricing, the brief has quietly grown an application inside it.

When not to write requirements yet

Sometimes the honest output of this exercise is a decision not to brief anyone. If you cannot describe the core workflow because the process itself changes every week, the process needs designing before it needs automating — software freezes whatever you pour into it, and freezing chaos gives you fast, expensive chaos. Run the workflow manually on a spreadsheet for a month, write down what stabilises, and brief that.

The other stop sign is coverage. If an off-the-shelf tool handles 90% of the job at $30 a month, the requirements page you should write is a configuration checklist, not a development brief. Custom work earns its keep when the remaining 10% is where your margin or your differentiation lives, or when the monthly per-seat arithmetic overtakes a one-off build. A week spent honestly configuring existing tools is the cheapest requirements-validation exercise there is, and a good development team will tell you the same on the first call.

From one page to a working product

Once the page exists, share it before anyone quotes, and judge teams partly on how they respond to it. A good team will push back on at least one thing — a feature to defer, an integration that is harder than it looks, a workflow step that needs a decision. Silence followed by a number is a warning sign.

If you want a second pair of eyes on your draft, we read requirements pages on our free 30-minute intro call and reply with a written fixed quote — always between $500 and $2,500 — within one working day. Alternatively, browse our use-case pages: each one is effectively a completed requirements page with a price and timeline attached, and finding the closest match to your idea is a fast way to sanity-check your own scope.