Writing Clear Requirements
Chapter 3: Techniques for crystal-clear communication
Write Like a Pro: Clear, Actionable Requirements
The SMART Framework
Every requirement should be:
- Specific: No ambiguity about what's needed
- Measurable: Clear criteria for completion
- Achievable: Technically feasible with available resources
- Relevant: Directly supports business objectives
- Testable: Can be verified when complete
Do's and Don'ts
DO
Use active voice:
"The system shall send an email when inventory reaches minimum level"
DON'T
Use passive voice:
"An email should be sent when minimum levels are reached"
DO
Be specific with numbers:
"Response time must be under 2 seconds for 95% of queries"
DON'T
Use vague terms:
"The system should be fast"
DO
Define terms:
"Active customer: any customer with a purchase in the last 90 days"
DON'T
Assume understanding:
"Show active customers" (What makes a customer active?)
Power Words for Requirements
Use These Action Words:
- Calculate, Validate, Generate
- Display, Hide, Enable, Disable
- Create, Update, Delete, Archive
- Send, Receive, Process, Store
- Authenticate, Authorize, Log
Avoid These Vague Terms:
- "User-friendly" (be specific)
- "Flexible" (define the flexibility)
- "Intuitive" (describe the flow)
- "Robust" (specify error handling)
- "Etc." (list everything)
The User Story Format
As a [user type], I want to [action], so that [benefit]
Examples:
- "As a warehouse manager, I want to see low stock alerts on my dashboard, so that I can reorder before stockouts"
- "As a sales rep, I want to check real-time inventory during calls, so that I can promise accurate delivery dates"
- "As an accountant, I want automated stock valuation reports, so that I can close books faster each month"
Acceptance Criteria Template
Given [initial context]
When [action occurs]
Then [expected outcome]
Example:
Given a product with minimum stock level of 50 units
When the available quantity drops to 50 or below
Then the system sends an email to the warehouse manager within 5 minutes