Documenting Requirements in Natural Language Flashcards
Full-fledged requirements specifications are typically needed when:
- Customers want contractually fixed requirements, costs and deadlines
- Systems are built by an external contractor based on a set of given requirements (outsourcing)
- In regulated environments where regulators check compliance of developed systems to their
requirements
Requirements in agile development
- No classic requirements specification document (unless mandated by regulators)
- Various artifacts / work products that
- specify requirements: Vision, stories, use cases, etc.
- have requirements-related content: Prototypes, mock-ups, storyboards, roadmap, early product versions (e.g., MVP– minimum viable product)
- Value-driven creation of artifacts
Agile requirement specification artifacts
- Requirements primarily captured as a collection of user stories, organized in a product backlog
- A system vision provides an abstract overview of the system to be developed
- On an intermediate level of abstraction, epics and features can serve to group user stories
- Stories may be sub-divided into tasks
- Use cases/scenarios and other models may be
used to provide structure and context
Aspects to be documented independently of any language, method, and artifact
functionality
performance
specific qualities
constraints
Functionality
- Data: Usage and structure
- Functions: Results, preconditions, processing
- Behavior: Dynamic system behavior as observable by users
- Both normal and abnormal cases must be specified
perfromance
- Data volume
- Reaction time
- Processing speed
- Specify measurable values if possible
- Specify more than just average values
specific qualities
“-ilities” such as
* Usability
* Reliability
* etc.
constraints
- Restrictions that must be obeyed / satisfied
- Technical: given interfaces or protocols, etc.
- Legal: laws, standards, regulations
- Cultural
- Environmental
- Physical
- Solutions / restrictions demanded by important stakeholders
Guidelines for agile requirements
- Standard template for writing user stories
- Organizing stories in a product backlog
- General guideline: do things only if they add value
language options
informal: natural language
semi-formal: structural models, interaction models (typically diagrams)
formal: formal models
General rules for requirements documentation
- Specify requirements as small, identifiable units whenever possible
- Record metadata such as source, author, date,
status - Use structure templates
- Adapt the degree of detail to the risk associated with a requirement
- Specify normal and exceptional cases
- Don’t forget quality requirements
and constraints
Natural language
Specifying with natural language
- The system shall …
- The oldest…
…and most widely used way
– taught at school
– extremely expressive - But not necessarily the best
– Ambiguous
– Error-prone
Problems with natural language requirements
- Who does this?– Passive voice
- When does this happen?– Vague requirement
- For whom?– Incomplete phrase structure
- What about free access promotions?– False all-quantification
- Faster than what?– No reference point
- Two requirement in one sentence
- Which data precisely?–Unspecific noun
Phrase template
[<Condition>] <Subject> <Action> <Objects> [<Restriction>]</Restriction></Objects></Action></Subject></Condition>
Some rules for specifying in natural language
- Use active voice
- Use terms as defined in the glossary
- When using adjectives in comparative form, specify a
- reference point: “better”→”better than…”
- Scrutinize all-quantifications: “every”, “always”, “never”, etc. → seldom hold without any exceptions
- State every requirement in a main clause. Use subordinate clauses only for making the requirement more precise
- Attach a unique identifier to every requirement
persona
paints a picture of a type of a product user
Personas, Scenarios & User Stories cycle
persona inspires scenarios, which are developed into stories, which then define features
persona description
namely, personalization, relevance, education, and job related
Scenarios
- Aim is to discover the product features that will tempt users to adopt your product rather than competing software
- Scenario is a narrative that describes a situation in which a user is using your product’s features to do something that they want to do
- The scenario should briefly explain the user’s problem and present an imagined way that the problem might be solved
Agile user stories
- A single sentence about a requirement
- Written from a stakeholder’s perspective
- Optionally including the expected benefit
- Accompanied by acceptance criteria for requirement
- Acceptance criteria makes the story more precise
agile user story template
As a <role> I want to <my> [so that <benefit>]</benefit></my></role>
product backlog
