Why Software Projects Go Wrong on Day One
Imagine sending the same message to three vendors: "We need an app to manage orders." The quotes come back several times apart, and all three are reasonable. One vendor pictured a simple online spreadsheet, another a full system with a mobile app, and the third guessed somewhere in between. You aren't comparing prices. You're comparing three readings of one sentence.
In Why Most Automation Projects Fail, we named scope creep without a spec as the number one killer. This post is the practical answer: how to write a lean spec before a single line of code. In our experience, a well-written two-to-five-page document is far more useful than a fifty-page one nobody rereads.
A Spec Is Not a Thick Document
Many business owners put off writing a spec because they picture a dense technical document. The goal is simpler than that: get everyone to share the same picture of what is being built, for whom, and when it counts as done.
The international standard for requirements engineering, ISO/IEC/IEEE 29148:2018, defines the process and the qualities of good requirements in detail. You don't need to follow it to the letter for a small or mid-sized business project. One principle from systems engineering is worth borrowing, though: requirements state what the system must do, not how to build it (SEBoK, System Requirements Definition). Frameworks, databases, and architecture are the technical team's job. Your job is to explain the problem and the outcome you expect.
Atlassian's guide to product requirements documents lists anti-patterns worth avoiding: specifying the whole project in detail before engineering starts, writing requirements without the team, and never updating the document once it's signed off. A good spec is clear enough to start from and light enough to change.
A Lean Spec Template
Here are the six sections we recommend. They're adapted from common structures, including Atlassian's template (goals, assumptions, user stories, open questions, and "what we're not doing").
1. Goal and business problem
One or two paragraphs: what goes wrong today, who it affects, and why it needs solving now. Keep solutions out of this section.
Example: "Warehouse admins copy orders from WhatsApp into a spreadsheet by hand. Orders get mixed up, and stock reports only arrive at the end of the week."
2. Users and roles
List who uses the system and what they're allowed to do. Admins, cashiers, managers, and customers need different things, and this list becomes the basis for access control.
Fix: a simple table with each role, the rough number of users, and their main actions.
3. Key flows as user stories
The GOV.UK Service Manual says every user story should cover who the user is, what they need, and why. The usual format:
As a [user], I want to [do something], so that [goal].
The same guide calls the goal the most important part. If you can't write the "so that", reconsider whether the feature is needed at all.
Add acceptance criteria to each story, written as "it's done when …". For example:
- It's done when an admin can create a new order on one screen.
- It's done when stock drops automatically once an order is confirmed.
- It's done when a manager can download a daily report as an Excel file.
These criteria are the best tool you have against the end-of-project "I thought it was finished" argument.
4. Phase 1 scope and what's out
Separate clearly what ships in phase 1 from what waits. The out-of-scope list matters just as much: writing "no mobile app in phase 1" stops silent assumptions that only surface at the demo.
Fix: three columns: must have in phase 1, can follow later, and not doing. If everything lands in the first column, you haven't really prioritised yet.
5. Data, integrations, and constraints
Note the systems that must connect (accounting software, payment gateway, WhatsApp), the data to migrate, and non-functional constraints: expected users, operating hours, security needs, and regulation such as Indonesia's Personal Data Protection Law (Law No. 27 of 2022) if you store customer data. For integrations, see 5 API Integration Mistakes and our WhatsApp Business API guide.
6. Success measures and open questions
Decide how you'll know the project worked: time to enter an order, recording errors, report turnaround. Measure today's baseline first; without it there's nothing to compare against. Our ROI of AI integration post has a fuller framework.
Finish with open questions, the things you don't know yet. Systems engineers mark uncertain values as "TBD" and track them until resolved. Writing down uncertainty honestly beats guessing.
Using the Spec to Get Fair Quotes
The same spec, sent to every vendor, turns quotes into a like-for-like comparison.
- Send the same document to every vendor, out-of-scope list and open questions included.
- Ask for a breakdown per feature or story, not a single total. A big gap on one feature usually means a different interpretation.
- Watch the questions vendors ask back. Vendors who ask about flows, data, and edge cases are reading your document seriously.
- Ask for written assumptions in each quote. Mismatched assumptions are the main source of mid-project disputes.
- Agree on a change process. Scope will change; what matters is how changes are logged, priced, and approved.
If you're still weighing custom software against a SaaS subscription, this spec is also the main input to our build vs. buy framework.
Mistakes We See Often
1. Writing solutions instead of problems
"We need a dashboard with 12 charts" is a solution. The problem might be "managers don't see critical stock until it's too late", which one alert could fix.
Fix: for every feature, ask "what problem does this solve?" and write the answer down.
2. Leaving out day-to-day users
Specs written only by leadership tend to miss the exceptions staff handle daily: returns, partial orders, instalment payments.
Fix: interview at least one person from each role before calling the document final.
3. Freezing the spec
Atlassian names stale documentation as one of the main challenges. A spec is a living document.
Fix: give the document one owner and log every change with a date and a reason.
Checklist Before You Contact Vendors
- Business goal written without naming technology.
- Every user role listed.
- Key flows written as user stories with "it's done when …" criteria.
- Phase 1 scope and out-of-scope items separated.
- Systems to connect and data to migrate recorded.
- Success measures defined, with today's baseline measured.
- Open questions listed, not guessed.
The AY Labs Approach
We don't start projects by writing code; we start by building the spec with you. If you come with a short brief, we help turn it into user stories, acceptance criteria, and an agreed phase 1 scope before the final quote. If you already have a document, we read it critically and send back a written list of assumptions and open questions. That way every number in our quote traces back to a feature, and changes along the way follow a clear process. If you're preparing a software project, we're happy to help tighten the spec first.
