Writing Feature Specifications in English: Structure and Vocabulary
Learn the vocabulary and structure for writing feature specifications — acceptance criteria, scope, assumptions, edge cases, and success metrics.
Introduction
A feature specification (or feature spec) is a written document that defines what a feature should do, who it is for, and how success will be measured. Writing a clear spec in English is a critical skill for engineers moving into senior or lead roles, and for anyone working in cross-functional teams where product managers, designers, and developers need a shared source of truth. A well-written spec prevents wasted work, reduces scope creep, and aligns stakeholders before a line of code is written.
The Structure of a Feature Specification
A good feature spec answers six questions: why, what, who, how, what not, and how will we know it worked. Most spec templates cover these in a consistent order.
Purpose and context:
- “This feature aims to allow users to schedule report delivery without requiring manual intervention each time.”
- “The goal of this specification is to define the behaviour of the notification preference centre for mobile users.”
- “This document describes the requirements for the CSV export feature requested by enterprise customers in Q1.”
The phrase “this feature aims to…” is the standard opener because “aims” signals intent without over-committing to a single implementation. Avoid “this feature will allow” if there are still unknowns — use “aims to” or “is intended to” instead.
User and stakeholder context:
- “The primary user for this feature is an operations manager who runs weekly performance reports.”
- “Key stakeholders include the billing team, the data platform team, and the head of customer success.”
- “This feature was requested by enterprise accounts representing approximately 60% of ARR.”
Writing Clear Acceptance Criteria
Acceptance criteria are the specific, testable conditions that must be true for the feature to be considered complete. They are the most important part of any spec.
Use “given / when / then” (Gherkin) format for precision:
- “Given a user is logged in as an admin, when they navigate to the billing page, then they should see all active subscriptions listed with their renewal dates.”
- “Given the export is triggered, when the file exceeds 10,000 rows, then the system should split the output into multiple files of 5,000 rows each.”
Or use a numbered list for simpler criteria:
- “The user can select a date range of up to 90 days.”
- “The export includes all columns visible in the current table view.”
- “An email is sent to the user when the export is ready to download.”
- “If the export fails, the user sees an error message with a reference code.”
Common mistakes to avoid:
- “The feature should be fast.” — This is not testable. Write: “The export should complete within 30 seconds for datasets under 5,000 rows.”
- “The UI should be intuitive.” — Not testable. Write: “The export button should be visible on the table toolbar without scrolling.”
Defining Scope and Flagging What Is Out of Scope
One of the most valuable things a spec can do is clearly state what is not included in this version.
In scope:
- “This specification covers the initial CSV export for the orders table only.”
- “The feature includes email notification upon export completion.”
Out of scope:
- “The following are out of scope for this release: PDF export, scheduled exports, and column customisation.”
- “API access to the export endpoint is out of scope and will be addressed in a future iteration.”
- “Localisation of the export file format is not included in this version.”
Writing explicit out-of-scope sections prevents the feature from growing during development as stakeholders add “just one more thing”. It also protects the engineering team by giving them a written reference when pushing back on late additions.
Flagging Assumptions, Dependencies, and Open Questions
No spec is written with perfect information. Being explicit about what you are assuming — and what you still need to find out — is a sign of strong technical writing.
Assumptions:
- “This feature assumes that the data warehouse is queryable within the p99 latency of 2 seconds for the required dataset sizes.”
- “We are assuming that the storage bucket for export files is already provisioned and accessible.”
- “This design assumes that the user has already completed email verification.”
Dependencies:
- “This feature depends on the authentication team completing the SSO integration before the export permission model can be tested.”
- “Delivery of this feature is dependent on the data platform team exposing the required API endpoint by sprint 12.”
Open questions:
- “Open questions include: What should happen to an export file after 30 days — should it be deleted automatically?”
- “It is not yet decided whether the export feature will be gated behind a paid plan.”
- “We need to confirm with legal whether the data included in exports falls under GDPR data portability requirements.”
Defining Success Metrics
A spec without success metrics makes it impossible to know if the feature achieved its goal after launch.
- “Success will be measured by a 20% reduction in support tickets requesting manual data exports within 60 days of launch.”
- “The feature will be considered successful if at least 30% of enterprise users trigger an export within the first month.”
- “We will track time-to-export as a key performance metric, with a target p95 of under 45 seconds.”
Key Vocabulary
| Term | Definition |
|---|---|
| acceptance criteria | Specific, testable conditions that define when a feature is complete |
| out of scope | Functionality explicitly excluded from the current specification |
| dependency | A requirement that must be fulfilled by another team or system before this work can proceed |
| assumption | A fact taken as true without full verification, which should be documented and later confirmed |
| edge case | An unusual or extreme input scenario that may cause unexpected behaviour |
| success metric | A measurable outcome used to evaluate whether a feature achieved its goal |
| stakeholder | A person or team with an interest in the outcome of the feature |
| open question | An unresolved decision or piece of information needed before implementation can proceed |
Practice Tips
- Write acceptance criteria before writing anything else. If you cannot write testable criteria, your understanding of the feature is not yet clear enough to hand off to engineers.
- For every “the system should be X” phrase, ask “how would we test that?” If you cannot write a test, rewrite the criterion until you can.
- Create an explicit “open questions” section and assign owners. Each open question should have a name next to it and a date by which it needs to be resolved.
- Read your spec from the perspective of an engineer who joined yesterday. If they could not implement the feature from your document alone, add more context.
Conclusion
A clear feature specification written in precise English is one of the highest-value documents an engineering team can produce. By mastering the vocabulary — acceptance criteria, out of scope, assumption, dependency, success metric — and the structure outlined in this guide, you will write specs that reduce ambiguity, align teams, and dramatically increase the chances that the right thing gets built. Good specs are an act of respect for your colleagues’ time.