How to Write Technical User Stories in English

User stories are the primary unit of work in most agile software development teams. Writing them well in English — with clear intent, unambiguous acceptance criteria, and testable outcomes — is a skill that product managers, developers, and QA engineers all need.

This guide covers the structure, vocabulary, and common mistakes of writing technical user stories.

The User Story Format

The “As a / I want / So that” Structure

The canonical user story format has three components:

• As a [type of user]
• I want [an action or capability]
• So that [a benefit or goal]

“As a registered user, I want to reset my password via email, so that I can regain access to my account if I forget my credentials.”

“As an administrator, I want to export a CSV of all active users, so that I can provide a report to the compliance team.”

“As a developer using the API, I want to receive a descriptive error message when I send an invalid request, so that I can debug my integration quickly.”

Why “So That” Matters

Many teams omit the “so that” clause. This is a mistake — the reason for a feature is as important as the feature itself. Without it, developers cannot make good trade-off decisions during implementation.

Without “so that”: “As a user, I want a filter on the search results.” With “so that”: “As a user, I want to filter search results by date, so that I can find the most recent content without scrolling through older results.”

Acceptance Criteria

What Acceptance Criteria Are

Acceptance criteria are the conditions that a user story must satisfy for the team to consider it complete. They define the scope of the story and make it testable.

“The story is complete when: (1) the user receives a password reset email within 60 seconds of the request; (2) the reset link expires after 24 hours; (3) the user is shown an error if they attempt to use an expired link.”

Writing Clear Acceptance Criteria

Acceptance criteria should be:

• Specific — not “fast” but “responds within 200ms under normal load”
• Testable — a QA engineer can verify it with a clear pass/fail
• Agreed — product, dev, and QA should all confirm the criteria before development starts

Weak criteria:

“The API should be secure.”

Strong criteria:

“All API endpoints require a valid JWT token. Requests without a token return HTTP 401. Requests with an expired token return HTTP 401 with an error message indicating token expiry.”

Given / When / Then (BDD)

Behaviour-Driven Development Vocabulary

BDD (Behaviour-Driven Development) is an approach that describes system behaviour in structured natural language. The Given/When/Then format is the standard way to write BDD scenarios.

• Given — the initial context or state
• When — the action or event that occurs
• Then — the expected outcome

Example:

“Given a registered user with a valid account, When they submit a password reset request with their registered email, Then they receive an email containing a password reset link within 60 seconds.”

Another example:

“Given a user is not logged in, When they attempt to access /dashboard, Then they are redirected to the login page with the URL /login?redirect=/dashboard."

"And” to Extend Scenarios

Use And to add additional steps without repeating Given/When/Then:

“Given a user has an item in their cart, And the item is in stock, When they proceed to checkout, Then the total price is calculated correctly, And the user is shown the available payment methods.”

Common Story Formats

Technical Stories

Technical stories describe work that does not deliver user-visible value directly but is necessary for the system. The “as a” subject is typically the team or the system.

“As the development team, we want to migrate the user database to PostgreSQL 16, so that we can take advantage of improved JSON performance and official long-term support.”

“As the system, I need to rotate encryption keys every 90 days, so that we comply with our security policy.”

Spike Stories

A spike is a time-boxed investigation or research task. The output is knowledge, not working software.

“Spike: Investigate options for adding real-time notifications. Time-box: two days. Output: a written comparison of WebSockets, Server-Sent Events, and polling, with a recommendation.”

Common Mistakes in User Story Writing

Writing From the System’s Perspective

Wrong: “The system should send an email when a user registers.” Better: “As a new user, I want to receive a welcome email after registration, so that I know my account has been created successfully.”

Including Implementation Details

User stories describe what the user needs, not how it should be built. Implementation details belong in technical notes or design documents.

Avoid: “As a user, I want the system to use Redis pub/sub to push notifications to my browser.” Better: “As a user, I want to receive browser notifications for new messages, so that I don’t have to keep refreshing the page.”

Stories That Are Too Large

A story that cannot be completed in a single sprint should be broken down.

“As a user, I want to manage my entire profile.” — Too large.

Break into:

“As a user, I want to update my display name.” “As a user, I want to upload a profile photo.” “As a user, I want to change my email address.”

Useful Vocabulary for User Stories

• Epic — a large body of work that can be broken down into multiple user stories
• Story points — a relative measure of effort, complexity, and uncertainty
• Definition of Done (DoD) — team-wide criteria that all stories must meet to be considered complete
• Definition of Ready (DoR) — criteria a story must meet before it can be pulled into a sprint

“This story is in the backlog but not yet ready — we need to clarify the acceptance criteria before it can be estimated.”

Well-written user stories reduce ambiguity, improve sprint predictability, and produce software that actually meets user needs. The language patterns in this guide are standard across agile teams — master them and you will communicate more effectively with every stakeholder in your delivery process.