3. Work products and documentation practices Flashcards
Work product (Artifact)
a recorded intermediate or final result generated in a work process
Characteristics of work products
- purpose
- size
- representation
- lifespan
- storage
Representation of requirements
- natural language
- templates
- models
Overview of RE work products
Single requirements
1. Individual requirement
2. User story
Coherent sets of requirements
1. Use case
2. Graphic model
3. Task description
4. External interface description
5. Epic
6. Feature
Documents of documentation structures
1. System requirement specification
2. Product and sprint backlog
3. Story map
4. Vision
Other WP
1. Vision
2. Textual note or graphic sketch
3. Prototype
Categories of Work Products w.r.t. lifespan
- temporary
- evolving
- durable
Temporary requirements
created to support communication and create shared understanding.
discarded after use, no metadata is kept
Evolving work products
emerge in several iterations
metadata shell be kept
change control might be needed
Durable work products
baselined or released
full set of metadata should be kept
strickt change procedure
Typical levels of abstraction for requirements
- business
- system
- component
may co-evolve
Typical levels of abstraction for requirements depends on
- subject to be specified
- purpose of the specification
do not mix the levels!
The level of details of the requirements depends on
- problem and project context
- degree of shared understanding of the problem
- degree of freedom left to designers and programmers
- ability of rapid stakeholder feedback
- cost vs value of a detailed specification
- Standards and regulations
General RE documentation guidelines
- Select a wp type that fits the intended purpose
- Avoid redundancy by referencing content instead of repeating the same content again
- Avoid inconsistencies between wp, particularly when they cover different aspects
- use terms consistently
- structure was appropriately
Work product planning
- in which wp shall the requirements be recorded and for what purpose
- which abstraction level to take
- up to which level of detail to document at each level
- how shall the requirements be represented in these was
Why define RE work products at an early stage
- Help in the planning of efforts and resources
- ensures that appropriate notations are used
- ensures that all results are recorded in the right wps
- ensures that no major reshuffling of information and final editing is needed
- helps to avoid redundancy
Aspects to be considered
- aspects within functional requirements
- quality requirements (usability, reliability, security, performance)
- constraints
- context and boundary / domain assumptionsG
Aspects within functional requirements
- Structure and data (requirements concerning static structure of the system and data the system must know)
- Function and flow (functions that a system shall provide and flow of control)
- State and behavior (state dependent behavior of a system - how react to external events, depending on the current state)
Performance requirements deal with
- Time
- Volume
- Frequency
- Throughput
- Resource consumption
Documenting quality requirements
Very difficult
- qualitative representation - hard to validate, ambiguous
- quantitative representation - measurable, but can be expensive to specify
- operationalised representations - quality requirement in terms of functional requirements for achieving the desired quality (i.e. no login possible)
Quantitative representation of quality requirements suffice in the following situations
- there is sufficient implicit shared understanding
- stakeholders, RE and developers agree on a known solution that satisfies the requirements
- stakeholders only want to give general quality directions and trust the developers to get the detail right
- short feedback loops are in place and can be detected early
- able to generalise from examples
- requirements are not safety critical
Categories of constraints
- technical
- legal
- organisational
- cultural
- environmental
- physical
- particular solutions required by stakeholders
Glossary content
- definitions for all terms that are relevant for the system
- all abbreviations and acronyms
- homonyms shell be avoided
helps to establish shared understanding
Glossary rules
- creation and maintenance (centrally over the entire project, one person responsible, stakeholders must agree on terminology)
- usage: must be mandatory
Standard best practice in RE
Frequently used requirements documents
- stakeholder requirements specification
- user requirements specification
- system requirements
- business requirements
- vision documents (conceptual imagination of a future system describing its key characteristics and how it creates value to the user)
Frequently used documentation structures
- product backlog
- sprint backlog
- story map (time & content)
The choice of documentation structure depends on
- development process chosen
- project type and domain
- contract
- size of the document
Prototype
A preliminary partial realisation of certain characteristic of a system
Usage of prototypes
- exploratory prototypes
- experimental prototypes
- evolutionary prototypes
exploratory prototypes
used to create shared understanding, clarify requirements, validate requirements at different levels of fidelity.
temporary work products discarded after use
specification by example
Evolutionary prototype
pilot systems that form the core of a system to be developed.
Types of exploratory prototypes (by degree of fidelity)
- wireframes
- mock-ups
- native prototype
Quality criteria for single requirements
- adequate !(true and agreed stakeholder needs)
- necessary
- unambiguous
- complete (self contained)
- understandable !
- verifiable
Quality criteria for RE work products
- consistent
- non-redundant
- complete (all relevant requirement at this point in time)
- modifiable (without degrading its quality)
- traceable
- conformant
Kano model
classifies features of a system into categories. looks at requirements from the perspective of the customers
- Delighters
- Satisfiers
- Dissatisfies
- (old) indifferent
- (old) hate
Q1. What would you feel if the feature was present in the system
Q2. What would you feel if the feature was absent?
NB all categories can be linked to distinct elicitation techniques
Delighters
- excitement factors / unconscious
feature the customer is unaware of
if absent, no-one complains, if present - can fe a differentiating feature
Satisfiers
something a customer specifically asks for
the more you put, the more people are happy
Dissatisfies
feature is so obvious, customer can’t imagine it not being part of the system
tacitly considered as must-haves
Elicitation techniques
- Gathering techniques
- Design and idea generation techniques
Careful: functional requirements are overrated and quality and constraints get less attention
Selecting the right elicitation technique
- type of system
- software development life cycle model
- people involved
- organisation setup
Gathering techniques an be subdivided
- questioning techniques
- collaboration techniques
- observation techniques
- artefact based techniques
Questioning techniques
- interviews
- quetionnairs
Interviews
- can be used to elicit high level requirements as well as specific ones
- typically requirements are satisfiers
- need clear goals and good preparation
Questionnaires
- larger group of stakeholders
- Quantitative questionnaires - confirm hypothesis or previously elicited requirements
- Qualitative quetionnaires - open ended questions - find new requirements
- Often a next step after obtaining a preliminary idea based on a series of interviews in order to validate these ideas with a large group
Collaboration techniques
- Workshops
- Crowd-based requirements engineering
Observation techniques
- Field observation
- Apprenticing
stakeholders are observed while they are engaged in their normal processing their usual context
NB Particularly useful for identifying dissatisfies
Artifact based techniques
- system archeology
- feedback analysis
- reuse of requirements
do not use stakeholders (directly) but rather work products.
NB can find satisfiers and dissatisfiers
Very useful if stakeholders are not available
Workshops
- umbrella term for group-oriented techniques
- a requirements workshop is a structured meeting in which a carefully selected group of stakeholders and content experts work together to define, create, refine and reach a closure on deliverables that represent user requirements
- yield good global insight in a short time
- both gathering and creativity technique
Crowed based requirements engineering
- elicitation is a participatory effort with a crowd of stakeholder, in particularly users
- diversity of talents an expertise
- need a platform for user engagement
Apprenticing
- the apprentice participates but does not interfere, they act as a novice I the field and are allowed to make mistakes
- aim - create deeper understanding of the domain, the business and processes
System archeology
- requirements are extracted from existing systems - legacy systems, competitor systems or analogous systems by analysing their documentation or implementation
- useful if an old system is replaced by the new one
- can detect many requirements / constraints that would not have been revealed otherwise
- need to check whether requirements are still valid and relevant
Feedback analysis
useful to gain insight into the user’s pains and gains
negative sources and critical remarks help to detect unnoticed dissatisfies
might even contains innovative ideas and be turned into delights
Reuse of requirements
many of requirements from old systems can be applicable to new - especially requirements that have been derived from an overarching domain model
can save time and money because can skip elicitation
only works if the requirements are up-to-date and are managed effectively
need to validate whether requirements are valid and relevant in the new situation
Creativity techniques
stimulate creativity in order to find or to create new requirements that cannot be gathered directly from the stakeholders because stakeholders are not aware of the feasibility of certain new features or technical innovations
stimulate out of the box and borderless thinking and elaboration of each other’s ideas
Preconditions for creativity
- chance and time for an idea to come up
- knowledge of the subject matter
- motivation
4, safety and security
Guidelines for brainstorming
- defer judgement by separating the finding of ideas from the analysis of ideas
- quantity prevails over quality
- free association and visionary thinking are explicitly desired
- taking on and combining expressed ideas is allowed and desired
- criticising other participants’ ideas is forbidden even if an idea seems absurd
- after the session, the ideas that have emerged are categorised, assessed and prioritised. Selected ideas then serve as input for further elicitation
Analogy techniques
- success of failure is influenced mainly by the selection of a proper analogy for the given problem
Steps
1. elaborate the aspects of the selected analogy in detail without referring to the original problem
2. transfer all identified aspects of the analogy back to the original problem
3. the resulting concepts and ideas will then be a starting point for additional elicitation
Basic principles of design thinking
- empathy (personas, empathy mapping, customer co-creation)
- creativity: diamond - divergent and convergent thinking
Divergent thinking
exploring an issue more widely and deeply - generating lots of different ideas
Convergent thinking
focuses, selects, prunes, combines these ideas into a single final delivery
General documentation guidelines
- select the wp type that fits the intended purpose
- avoid redundancy by referencing content instead of repeating the same content again
- avoid inconsistencies between WPs, particularly when they cover different aspects
- use terms consistenty as defined in the glossary
- structure WPs appropriately, for example by using standard structures
Problems with natural-language-based work products
- not optimised for unambiguous and comprehensive communication
- spoken - immediate feedback, written - harder detect ambiguities, omissions, inconsistencies
Rules for writing documentation
- write short well structured sentences. one requirement one sentence
- create well structured work products => hierarchical structures of parts, sections, subsections + document templates
- use uniform terminology
- avoid using vague or ambiguous terms and phrases
- know and avoid pitfalls of technical writing
Things to avoid in text requirements
- incomplete descriptions
- unspecific nouns
- incomplete conditions
- incomplete comparisons
Careful
1. passive voice (who is responsible)
2. universal quantifiers
3. nominalisation
Types of templates for natural language WPs
- phrase template
- form template
- document template
Phrase template
A template for the syntactic structure of a phrase that expresses an individual requirement or a user story in natural language
NB using phrase templates is a best practice when writing individual requirements in natural language and writing user stories
Phrase template examples
- ISO/IEC/IEE 29148 phrase template
- EARS template
Auxiliary verbs in the ISO/IEC/IEE 29148 phrase template
- shall - mandatory requirement
- should - not mandatory but strongly desirable
- may - suggestion
- will / present tense - factual statement that is not considered as a requirement
NB make sure there is a common understanding!
ISO/IEC/IEE 29148 phrase template
<Condition><Subject><Action><object><Restrictions>
When a valid card is sensed the system shell display "enter the pin" message on the dialog screen within 200ms
</Restrictions></object></Action></Subject></Condition>
EARS template types of requirements
Easy approach to requirements syntax
- ubiquitous requirements
- event-driven requirements
- unwanted behaviour
- state-driven requirements
- optional features
EARS: ubiquitous requirements
The <system> shall <system></system></system>
EARS: event-driven requirements
WHEN <optional> <trigger> the <system> shall <system></system></system></trigger></optional>
EARS: unwanted behavior
IF <optional> <trigger>, THEN the <system> shall <system></system></system></trigger></optional>
EARS: state driven requirements
WHILE <in> the <system> shall <system></system></system></in>
EARS: optional features
WHERE <feature> the <system> shall <system></system></system></feature>
Cohn’s user story template
As a <role> I want <requirement> so that <benefit></benefit></requirement></role>
NB every user story shell include acceptance criteria
Form template
A template providing a form with predefined fields to be filled in
Used to structure WPs of medium size (i.e. use cases)
Use case template
- Precondition
- Success end condition
- Failed end condition
- Primary actor
- Other actors
- Trigger (initiates execution of the use case)
- Normal flow
- Alternative flows
- Extensions (to the normal flow)
- Related information
Measurable quality requirement template
- ID
- Goal
- Scale
- Meter
- Minimum
- OK range
- Desired
Document template
A template providing a predefined skeleton structure of a document
help to systematically structure requirements documents
Limitation of the requirements in the natural language
- ambiguity
- confusion
- omission of requirements
- loose overview if the number of requirements is too big
- complexity
- abstraction
Model
An abstract representation of an existing part of reality or a part of reality to be created
A model is made for a specific purpose and a specific context
Use case
a set of possible interactions between eternal actors and a system that provide a benefit for the actor(s) involved
Actor
Represents the role performed by another system or persons that interact with the system
Requirements model
a conceptual model that depicts the requirements for the system to be developed
Properties of a model
- made for a specific purpose
- gives a representation of reality
- used to reduce information to enable understanding or focus on the part of the reality
Descriptive modeling
modelling existing original. shows current reality and reflects the requirements that are met
Prescriptive modelling
modelling an original to be created. what future reality is expected or required
How to reduce information
- compression or aggregation
- selection
Advantages of models
- elements and their connections are easier to understand
- focus on a single aspect reduces cognitive load
- reduced ambiguities and omissions
- higher potential of automated analysis and processing of requirements
Disadvantages of models
- keeping different models consistent with each other is hard
- integrating information from different models
- models focus primarily on functional requirements
- not every relevant item of information can be expressed in a model
Functional requirements are categorised in the following perspectives:
- structure and data (static)
- function and flow (sequence of actions)
- state and behavior (state dependent reactions to event)
Benefits of models
NB take inventory of goals and context
- specifying (primary functional) requirements
- decomposing a complex reality into well-defined and complementing aspects
- paraphrasing textual representation requirements in order to improve their comprehensibility
- validating textually represented requirements with the goal of uncovering omissions, ambiguities and inconsistencies
The quality of the model can be assessed against three criteria
- syntactic quality
- semantic quality
- pragmatic quality
Syntactic quality
extend to which a single model element, requirements diagram or requirements model complies with the syntactic specifications (i.e. contains elements that are not parts of the syntax or missused)
Semantic quality
the extent to which a single model element correctly and completely represents the fact
Pragmatic quality
the extend to which a single model elements suitable for the intended use - whether the degree of detail and abstraction level is appropriate for the intended use and whether the appropriate model is selected with respect to the domain or context (provided that purpose, context and stakeholders are known)
Context model
specify the structural embedding of the system in its environment, with its interactions to the users of the system as well as to other new or existing systems within the relevant context.
can reveal sources of requirements. The interfaces need to be defined later
Context models are frequently represented by:
- Data flow diagrams
- UML use case diagrams
- Tailored box & line diagrams
- SysML block definition diagrams
Data flow diagram
- structure analysis of the system => the system is represented by 1 process
- rectangle: terminator - sink and source of information / service in the system
- Arrows: flow of information, annotated by the information being transferred. no reference to how
DFD use case
- provides insights in the interaction of the system with its environment, e.g. interfaces, objects received, objects / information produced
- indicates a clear boundary between the system and its environment - helps to reach a common understanding of the system boundary
UML use case diagram elements
- Actor (user or system) - initiates the use case and receives benefit
- Use case - function that delivers benefits to the actor
- Association - does not document direction or data flow
- System boundary: scope of the system - separation between the actor and the boundary
UML use case diagram
- common approach to model the functional aspect of the system, its boundaries and its interactions
- describe functions in the scope from a user perspective
- includes use case specifications: preconditions, trigger, actions, postconditions, actors
Models for depicting structure and data
- Entity relationship diagram
- UML class diagrams
- SysML Block Definition Diagram
UML Class Diagram
depicts a set of classes and associations between them
UML class diagram notation elements
1 Class: set of objects that have a similar structure, behavior and relationships
2. Attribute: property of a class, has. type that restricts the values assigned to an attribute
3. Association: relates two classes to each other
4. Multiplicities: how many instances of the class at the corresponding association end can participate in the association to a given instance (0..* = zero or more, 0…1 - zero or one)
Modelling function and flow
- describe how the (sub)system shall transform input into output.
- can document from different angles (unlike data) => more than one model might be needed to document the requirements about function and flow
Common models for depicting function and flow
- UML case diagram
- UML activity diagram
- Data flow diagram
- Domain story model
- Business process modelling notation
UML Activity diagram
- elements for modelling actions and the control flow between actions
- can express who is responsible for what
- expresses the control flow of activities of a (sub)system
UML Activity diagram: basic notation elements
- start node: starting point of activity diagram
- end node: (can be multiple)
- control flow terminator: ends the activity flow
- Action/activity: non interruptible action on objects, results in a change in state of the system/result
- ## Action or control flow: transitions from one action state to another
- decision node: branches depending on a guard
- merge node: bring together multiple not concurrent flows
Synchronization - fork node: split into multiple concurrent calls
- join node: joins multiple concurrent flows back
Common model to represent behavior and state
- Statecharts
- UML state diagram
