Most custom software projects that go wrong don't fail because of bad code. They fail because the people building the software and the people who will use it had different pictures in their heads. Requirements are how you make those pictures match. The good news is that you don't need to be technical to write useful requirements — you need to describe your business clearly.
This guide is for business owners, operations managers and department heads who are about to commission a web app, mobile app or internal system.
Start with the problem, not the solution
Before listing features, write one page that answers:
- What problem are we solving? "Our service team misses AMC visits and invoices go out two weeks late" is better than "we need a CRM".
- Why now? Growth, customer complaints, a new contract, an audit, staff turnover?
- What does success look like? Measurable if possible: invoices within two days, zero missed visits, half the time spent on reports.
- What's out of scope for now?
This page is the reference point for every decision later. When someone suggests a new feature, ask whether it helps solve the problem on page one.
Describe the users
List each type of user: who they are, how many, what devices they use, where they work and how comfortable they are with technology. A field technician on a phone in a basement, a planner at a desk with two screens and a customer using a portal once a month have very different needs. Name a real person for each role if you can — it keeps requirements grounded.
Map the current workflow
Describe how work happens today, step by step, including the spreadsheets, WhatsApp messages, paper forms and phone calls. Collect samples: the job card, the Excel tracker, the report the customer receives. These artefacts tell developers more than pages of description. Note where things go wrong today — that's where the software must be most careful.
Describe the future workflow
Now describe how work should flow in the new system. A simple numbered list per process works well:
- Customer raises a complaint on WhatsApp or the portal.
- The coordinator checks the contract and assigns a technician.
- The technician receives the job on the app, travels, completes a checklist and captures a signature.
- The report is emailed automatically; the job moves to invoicing.
For each step, note who does it, what information they need and what they produce.
Write user stories with acceptance criteria
User stories break the workflow into buildable pieces. The common format is:
As a [type of user], I want to [do something] so that [benefit].
For each story, add acceptance criteria — specific conditions that must be true for the story to be considered done:
- The technician sees only jobs assigned to them.
- Jobs are sorted by scheduled time.
- Jobs remain visible without internet; changes sync when connected.
- A job can't be completed until mandatory checklist items are filled.
Acceptance criteria are where most misunderstandings are caught. They're also what you'll test against at the end.
Think about the exceptions
The happy path is easy. Real business is full of exceptions, and they're where most rework comes from. For each workflow, ask:
- What if the customer cancels or reschedules?
- What if the technician can't complete the job — parts missing, site locked?
- What if two people edit the same record?
- What if a mistake is found after an invoice is issued?
- What if a user leaves the company?
You don't need to solve every exception in phase one, but list them so they're consciously handled or deferred.
List the data
Describe the main things the system stores — customers, sites, equipment, jobs, products, orders — and the important fields for each. Note which fields are mandatory, which come from other systems and which must be unique. If you have existing data, say where it is, how much there is and how clean it is. Data migration is often underestimated.
Define roles and permissions
Who can see what, and who can change what? A simple table with roles across the top and actions down the side — view jobs, create jobs, approve quotes, see prices, export data, manage users — is enough. Permissions are hard to add cleanly later, so define them early.
Specify reports and dashboards
Managers often care most about the reports, yet reports are often left until the end. List the reports you need, who uses them, how often, and the filters and columns. Attach examples of reports you currently produce in Excel. If a number appears on a dashboard, define exactly how it's calculated.
Non-functional requirements
These describe how the system should behave rather than what it does:
- How many users, records and transactions should it handle now and in three years?
- Does the mobile app need to work offline?
- What languages are needed?
- Which browsers and devices must be supported?
- Any security, backup or data residency expectations?
- Any connections to existing systems — and do those systems offer an API or import/export?
Prioritise ruthlessly
Mark each requirement as must have for the first release, should have soon after, or could have later. A first phase that does the core workflow well, live in weeks, beats a giant release that takes a year. See our guide to planning a first phase.
Common gaps
- Requirements written by one manager without input from actual users.
- Only the happy path described.
- Reports left until the end.
- No mention of existing data.
- Everything marked as essential.
- "It should work like [famous app]" without explaining which part.
Working with your development partner
Treat your requirements as the start of a conversation. A good partner will ask questions, challenge assumptions, suggest simpler approaches and turn your document into a detailed specification during discovery. Review prototypes and early builds frequently — seeing software is the fastest way to discover what was missed.
Corposol helps businesses turn workflows into custom software. Talk to us — bring your spreadsheets and forms.
Frequently asked questions
Do I need a formal requirements document before talking to developers?
No. A clear description of the problem, the people involved and the main workflows is enough to start. A good development partner will help turn it into detailed requirements during discovery.
How detailed should requirements be?
Detailed enough that two people would build roughly the same thing from them. For the first phase, focus on the core workflows in detail and list later ideas briefly.
What is a user story?
A short description of something a user needs to do and why — for example, 'As a technician, I want to see today's jobs on my phone so I can plan my route.' Each story gets acceptance criteria that define when it's done.
Should we include screen designs?
Rough sketches or screenshots of current spreadsheets and forms help a lot. Polished designs are usually produced during the project, based on the requirements.
What do people most often forget?
Exceptions and edge cases, permissions (who can see and change what), reports, data migration from existing systems, and what happens on mobile with poor connectivity.
