A technical spec is a written description of what software should do, detailed enough that a developer can estimate the work and agree a price. Many bad quotes start with a vague brief: “an app like Uber, but for tutors”. Developers then either pad the price to cover the unknowns or quote low and argue about scope later. You do not need to be technical to write a useful technical spec. You need to be specific about people, actions, data and limits.
What a quote depends on
A developer estimating a project is really asking four questions. How many different kinds of user are there, and what can each do? How many screens and steps? What data is stored and where does it come from? What other systems does it connect to? Every section below answers one of those questions, plus the limits that change the size of the job.
What to put in a technical spec
Purpose and success
Two or three sentences on the problem and how you will know the software has solved it. “Members of our three gyms in Bengaluru book classes by WhatsApp, and front-desk staff spend about two hours a day on it. We want members to book and cancel online, and staff to see each class list on a tablet.” The numbers can be rough, but they help the developer understand what matters most.
Users and roles
List each kind of user and what they can do. Member: book, cancel, see history. Front desk: see class lists, mark attendance. Owner: everything, plus reports and pricing. Each extra role adds screens and permission rules, so this list has a direct effect on the price.
Key flows
Write the main tasks as numbered steps, from the user’s point of view. “1. Member opens the link. 2. Sees this week’s classes. 3. Taps a class. 4. If spaces remain, confirms; if full, joins the waiting list.” Include what happens when things go wrong: no spaces, payment failed, member cancels late. Edge cases are where estimates go wrong.
Screens
Rough sketches on paper or a simple wireframe for each screen are enough. A photo of a notebook page beats three paragraphs of description. If you have a vibe-coded prototype, link it and say which parts are right and which are placeholders.
Data
List what the system stores: members (name, phone, email, membership type), classes (time, trainer, capacity), bookings. Say which fields are personal data, and where existing data lives today, because importing old records from spreadsheets is real work that often gets missed.
Connections to other systems
Name every outside service: payment provider, email or WhatsApp messaging, accounting software, calendar. For each, say whether you already have an account and who owns it. An integration with a well-documented API is a known quantity; an integration with an old in-house system may need investigation before anyone can price it.
Limits and constraints
These change the size of the job more than founders expect.
- Platforms: web only, or iPhone and Android apps too?
- Languages: English only, or Arabic and Hindi as well? Right-to-left layouts add design work.
- Scale: tens of users or tens of thousands?
- Data location and accessibility requirements from clients or regulators.
- Deadline, and any fixed date such as a launch event.
Out of scope
Say clearly what is not included in this phase: “No trainer payroll. No mobile app in phase one.” In our view, this section prevents more disputes than any other.
How you will judge it is done
For each key flow, write one or two acceptance checks in plain language. “Given a class is full, when a member tries to book, then they are offered the waiting list.” These become the developer’s test cases and your sign-off list.
Format and length
For a small product, six to ten pages is usually plenty. Use headings, numbered steps and short lists so a developer can refer to “flow 3, step 4” in a question. Keep one version, date it, and record changes as you agree them.
A good spec also makes quotes comparable. If three developers price the same document, you can see who understood it. That is why we work from a written scope with price and timeline agreed before work starts. If you would like help turning an idea into a spec, our strategy work covers product scoping, or you can contact us to talk it through.
Frequently asked questions
How long should a technical spec be?
Long enough to answer who uses the software, what they do, what data it stores and what it connects to. For a small web or mobile product that is often six to ten pages including sketches. Length matters less than precision: numbered flows and clear limits are more useful than long descriptions.
Do I need wireframes for a technical spec?
You need some picture of each screen, but it can be rough. Hand-drawn sketches, screenshots of apps you like with notes, or a vibe-coded prototype all work. The aim is to show what appears on each screen and what each button does, so the developer is not guessing at the layout or the flow.
What if I do not know the technical details?
Leave them out and describe the behaviour instead. Say what users do, what data is stored and which outside services you use, and let the developer propose the technology. Flag anything you are unsure about as an open question. A good developer will ask follow-up questions before quoting rather than guess.