Most app projects that go over budget do not fail in the code. They fail in the gap between what the founder pictured and what the developer understood. The founder says "a simple booking app." The developer hears something. Six weeks later, both are surprised.
Knowing how to write an app spec closes that gap. You do not need technical knowledge to do it well. In fact, the best specs from non-technical founders are often clearer than ones written by engineers, because they describe what users need instead of how the software should work. That is exactly what a developer needs from you.
This guide gives you a structure you can fill in over an afternoon, a simple way to describe features so they can be built and tested, and the mistakes that make quotes balloon.
What a spec is for
An app spec, sometimes called a requirements document or a product brief, does three jobs:
- It gets you an accurate quote. Developers price uncertainty. A vague brief gets a padded estimate, or a low one that grows later.
- It defines "done." When a feature is delivered, you need a way to check it. The spec is that checklist.
- It forces you to decide. Writing a spec exposes every question you have not answered yet. Better to find them now than in the middle of the build.
A spec is not a technical design. You do not choose databases, frameworks, or architecture. You describe who the users are, what they need to do, and what success looks like. The developer decides how.
The one-page structure
For a first version, aim for something short enough that a developer will actually read all of it. Here is a structure that works.
1. The one-sentence summary
What the app does and for whom. "A booking app that lets clients of independent yoga teachers book and pay for classes." If you cannot write this sentence, you are not ready to write the rest.
2. The users
List each type of person who uses the app, and what they are trying to get done. Most first versions have one or two: for example, "client" and "teacher." If there is an admin who manages things behind the scenes, list them too, even if the admin is you.
3. The core journey
Describe, step by step, the main thing a user does from first opening the app to getting value. For the booking app:
- Client opens a link from the teacher's Instagram.
- Sees the week's classes.
- Picks a class, creates an account, pays.
- Gets a confirmation and a reminder before class.
This journey is the heart of your first version. Everything in the spec should serve it.
4. The features, as user stories
Now break the journey into features, each written as a short user story with acceptance criteria. More on this format below, because it is the most useful habit in the whole document.
5. Out of scope
A list of what this version will not do. This section prevents more scope creep than any other.
6. Constraints and context
Platforms (web, iPhone, Android), languages, any services you already use (like a payment provider or an email tool), deadlines, budget range, and anything regulated, like health or children's data.
7. Examples and references
Screenshots of apps you like, with a note on what specifically you like about each. "The calendar view in app X" is far more useful than "make it look modern."
User stories: the format that makes features buildable
A user story describes a feature from the user's side, in one sentence:
As a [type of user], I want to [do something], so that [I get some benefit].
For example:
As a client, I want to see all of this week's classes on one screen, so that I can quickly find a time that works for me.
The "so that" part matters more than it looks. It tells the developer why the feature exists, which helps them make sensible decisions you did not think to specify. If the reason is speed, they will not bury the schedule behind three taps.
Acceptance criteria: how you will check it
Under each story, list the conditions that must be true for the feature to count as done. Write them as plain statements a non-technical person can test by using the app:
As a client, I want to cancel a booking, so that I can free my spot if my plans change.
- A client can cancel any booking up to 12 hours before the class starts.
- After cancelling, the spot becomes available to other clients immediately.
- Cancellations within 12 hours are not allowed, and the app explains why.
- The client receives an email confirming the cancellation.
- The teacher sees the cancellation in their class list.
Three to seven criteria per story is usually enough. Cover the normal case first, then the obvious exceptions: what happens when something goes wrong, when a limit is reached, or when the user does something unexpected.
Notice what these criteria do not say. They do not say "a red cancel button in the top right." Describe what the user can do and what happens, not how the screen looks, unless the look genuinely matters. That leaves room for the developer to use standard patterns, which are cheaper to build and easier for users.
The questions that hide inside features
Writing acceptance criteria will surface questions like these. Answer them in the spec, because each one changes the build:
- Accounts: Do users sign up with email, Google, Apple, or all three? Can they use the app without an account?
- Payments: One-off purchases or subscriptions? Refunds? Which currency?
- Notifications: Email, push, SMS? What triggers each one?
- Roles: What can each type of user see and change? Can a teacher see other teachers' clients?
- Admin: How will you fix problems, like a wrong booking or a refund? If the answer is "I will ask the developer," that is a recurring cost.
The out-of-scope list
Every founder has a mental list of features for "later." Write it down explicitly in the spec as out of scope for this version. For example:
- Group chat between clients
- A teacher marketplace for discovery
- Discount codes
- Multiple languages
- An Android app (web only for version one)
This does two things. It tells the developer not to quietly build foundations for features you have not committed to, which inflates the quote. And it protects you from yourself when, three weeks into the build, a "small addition" starts to sound like a good idea. If it is on the list, it waits.
Mistakes that blow up quotes
Describing everything at the same priority. Mark each story as "must have for launch" or "nice to have." Developers can then quote the must haves firmly and price the rest separately.
Using words that mean different things to different people. "Simple," "intuitive," "like Uber," and "social features" are not specifications. Replace each with a concrete description of what the user does.
Leaving out the boring parts. Password reset, account deletion, error messages, privacy policy, terms, email confirmations, and admin tools are not exciting, but they take real time to build. If they are missing from the spec, they will be missing from the quote, and then they will appear as extras.
Specifying the solution instead of the problem. "Use a machine learning model to recommend classes" locks the developer into an expensive approach. "Show each client the classes they are most likely to book, based on what they booked before" lets them propose something simpler that does the same job.
Writing it alone and never revisiting it. Share the draft with a developer before asking for a final quote, and invite questions. Their questions are the cheapest feedback you will get on the whole project. Update the spec with every answer.
How long should it be?
For a focused first version, the summary, users, journey, and out-of-scope list usually fit on one or two pages. The user stories might add a few more. If your spec runs past ten pages, that is often a sign the first version is too big, not that the spec is too detailed.
Learning how to write an app spec is really learning how to make decisions early, in writing, while changes are still free. A clear spec will not guarantee a smooth build, but a vague one almost guarantees a painful one.
Originally published at https://foundyra.com/news/how-to-write-an-app-spec
Top comments (0)