A good specification explains what success looks like
A specification is not just a list of screens. It is a shared understanding of what the software must achieve, which users it serves, what business rules apply and how both parties will judge whether the result is acceptable.
The document does not need to dictate every technical decision. It should define the problem and the important behaviours clearly enough for meaningful planning and quotations.
1. Business objectives
Explain why the project matters. Identify current frustrations and the intended improvement. Describe practical measures of success without inventing unrealistic financial targets.
2. Users and responsibilities
List user groups, their roles, permissions and key activities. Consider administrators, managers, frontline users, external partners and support personnel where relevant.
3. Core workflows
Describe the important steps from beginning to end. Include handoffs, decisions, approvals and what should happen when something goes wrong.
4. Functional requirements
Define the capabilities the system needs. Distinguish essentials for an initial release from later enhancements. Use examples to make abstract requirements concrete.
5. Business rules and calculations
Document pricing logic, allocations, contract conditions, exception rules and how historical changes affect calculations. Clarify who may override or approve them.
6. Data and migration
Identify existing data sources, important records, data quality issues, retention needs and migration responsibilities. Confirm which data is authoritative.
7. Integrations
List external systems, available interfaces, information flows, authentication and ownership of third-party access. Include error and recovery requirements.
8. Security and non-functional needs
Consider access control, audit information, backup, reliability, performance expectations, accessibility and relevant regulatory requirements appropriate to the project.
9. Testing and acceptance
Write meaningful acceptance criteria around real scenarios. Include exceptional conditions, edge cases and any critical calculation comparisons.
10. Delivery assumptions and exclusions
Identify responsibilities, approvals, dependencies, environments, milestones and what is explicitly outside the quoted scope. Unstated assumptions often cause the most serious disputes.
11. Ownership and ongoing support
Agree what the client will own, how pre-existing components are licensed, what documentation will be supplied and how maintenance will work after launch.
How detailed should discovery be?
The level of detail depends on complexity. A focused internal tool does not need the same documentation as a multi-party platform with intricate commercial rules. What matters is that the uncertainty is visible before contractual commitments are made.
Using the plan to obtain quotations
A customer-owned plan can help competing suppliers price against a common set of requirements. Compare the assumptions and exclusions carefully, not only the total price.
