Image by Unsplash

Clarity Required

A Cheat Sheet for Writing Requirements
Last edited: April 2021
Estimated reading time: 2 minutes

Contains:
• Basics of requirements
• Quality of good requirements
• Dealing with ambiguity
• Considerations for documentation

Disclaimer: The work presented in this case study was performed in a personal capacity as a hypothetical design exercise.

Image by Unsplash

DEFINITIONS

IEEE’s definition of a requirement, paraphrased:
“A compulsory condition / capability that: -  

  • Solves stakeholder problem, or
  • Achieves stakeholder objective, or
  • Satisfies contract, standard, specification, or other formally imposed documents, or
  • Documentation that represents the above."


Common Categories of Requirements, by use sequence:

  1. Business requirements:- The Why or purpose of the product defined as tangible or strategic value to the business.
  2. Business rules:- Constraints on the how of the product to be appropriate/ successful; usually regulatory, policies, budgets, image considerations.
  3. User requirements:- Core functionality for users. Formats include: use cases, user stories, user flow, storyboards, context scenarios.
  4. Functional requirements:- Inputs, outputs and behavior processed by product. Formats include: resources, deliverables, data flow diagrams.
  5. Non-functional requirements:- Performance quality. Commonly accuracy, dependability, security, usability, efficiency, performance, and maintainability.
  6. External interfaces:- Relationships with external entities, commonly media, protocols, formats, and levels of compatibility. 
  7. Development constraints:- For creation of the product, i.e. platforms, computing power.
  8. Transitional constraints:- Occurs during transition of the product.


Use Case Common Items:

  • Participating Actors - Description on roles of engagers
  • Goal - Intended objectives
  • Trigger - Events that prompt use case to begin
  • Pre-condition - Conditions for the use case to occur
  • Post-condition - Conditions that are true after use case completes
  • Basic flow - Step by step description of what occurs in a sunny-day scenario
  • Alternate flow - Description of alternative scenarios outside sunny-day
  • Exceptions - Scenarios where the use case will not work/ apply
  • Qualities - Performance quality aspects. See non-functional requirements

QualitIES OF GOOD Requirements


Good User Stories are INVEST

  1. Independent - Meaningful without referring to other user stories
  2. Negotiable - solution agnostic
  3. Valuable - to the client and end user
  4. Estimable - allows for time estimates 
  5. Small - developed within preferred time period
  6. Testable - clear criteria and tests for evaluation 


And...

  • Correct - aligned to client/ end users’ vision
  • Complete - not missing key items (i.e user story mapping)
  • Clear - single interpretation of success
  • Consistent - does not conflict another user story
  • Feasible - realistically implemented
  • Traceable - mechanism to track code, tests and bugs

Dealing with Ambiguity


Ambiguous requirements uses words that:-

  1. Can be interpreted in multiple ways
  2. Does not contain the complete, necessary details


11 Categories of common ambiguous words:

  1. Indirect:- possible but not specified i.e. should, could, may, will, often, when applicable
  2. Vague:- non specific, multi definition i.e. processed, handled, item, when applicable
  3. Persuasion:- assumes knowledge i.e. clearly, obviously, surely
  4. Completion:- words to reduce sentence lengths  i.e. also, etc, and so on
  5. Qualifiers:- qualifies/ impose conditions i.e. only, all, every, none, never, always
  6. Comparative:- compares ill-defined aspects i.e. x-er, x-est
  7. Quantities:- Generic, ill-defined i.e. few, some, most
  8. Pronouns:- that replace specific nouns and terms i.e. it, that, them, those
  9. Positional:- relations to specific positions i.e. after, before, following, last
  10. Temporal:- relations to specific time i.e. when, for, until, latest, current
  11. Joining:- combines 2 sentences i.e. and, or 


3 Ways to Fight Ambiguity

  1. Pre-scan and challenge to interpret in different ways
  2. Construct and share a glossary
  3. Clarify by asking questions

Considerations for documentation


Documentation should be created only to the extent needed to ensure clear understanding by the team.”   - BABOK 4.4


Consideration before starting

  • What is the purpose for the documentation?
  • Who’s reading it and why?
  • Which stage of the project/ product is in?
  • Are there suitable templates to kickstart?
  • Were the contents clarified with stakeholders?


Common sections/ contents:

  • Key Details (Bullet points)
  • Executive Summary
  • Project Background/ Overview
  • Scope: In Scope and Out of Scope
  • Current Process Flow
  • Future/ Intended Process Flow
  • Essential Use Cases + Diagram
  • Assumptions
  • Limitations
  • Risk/ Risk Plan
  • Signatory/ Approvals
  • Glossary


Columns for table formatting of requirements:

  • ID#
  • Priority
  • Description
  • Rationale
  • Use Case ID
  • Impacted Stakeholder
  • Parent ID
  • Source
  • Dependancies
  • Conflicts
Make a COPY