Paul Gerrard

First published 12/04/2012

 

In this approach, the technique involves taking a requirement and identifying the feature(s) it describes. For each feature, a story summary and a series of scenarios are created and these are used to feedback examples to stakeholders. In a very crude way, you could regard the walkthrough of scenarios and examples as a ‘paper-based’ unit or component test of each feature.

What do you mean ‘unit or component test’?

A story identifies a feature and includes a set of examples that represent its required behaviour. It is not a formal component specification, but it summarizes the context in which a feature will be used and a set of business test cases. Taken in isolation, the story and scenarios, when compared with the requirement from which it is derived, provide a means of validating the understanding of the requirement.

Rather than test the functionality of a feature (which is done later, by developers usually), the story and scenarios test the requirement itself. When anomalies are cleared up, what remains are a clarified requirement and a story that identifies a feature that provides a set of clarifying examples. The definition of the identified feature is clarified and validated, in isolation – just like a component can be tested and trusted, in isolation.

The scenarios are limited in scope to a single feature but taken together, a set of stories validates the overall consistency and completeness of a requirement with respect to the feature(s) it describes.

Creating Stories and Scenarios – DeFOSPAM

DeFOSPAM is the mnemonic the Business Story Method™ uses to summarise the seven steps used to create a set of stories and scenarios for a requirement that allow us to comprehensively validate our understanding of that requirement.

• Definitions
• Features
• Outcomes
• Scenarios
• Prediction
• Ambiguity
• Missing

The number of features and stories created for a requirement are obviously dependent on the scope of a requirement. A 100 word requirement might describe a single system feature and a few scenarios might be sufficient. A requirement that spans several pages of text might describe multiple features and require many stories and tens of scenarios to fully describe. We recommend you try and keep it simple by splitting complex requirements.

D – Definitions

If agreement of terminology, or feature descriptions cannot be attained, perhaps this is a sign that stakeholders do not actually agree on other things? These could be the goals of the business, the methods or processes to be used by the business, the outputs of the project or the system features required. A simple terminology check may expose symptoms of serious flaws in the foundation of the project itself. How powerful is that?

On the one hand, the need for definitions of terms used in requirements and stories arises as they are written and should be picked up by the author as they write. However, it is not uncommon for authors to be blind to the need for definitions as they might be using language and terminology that is very familiar to them. Scanning requirements and stories to identify the terms and concepts that need definition or clarification by subject matter experts is critical.

Getting the terminology right is a very high priority. All subsequent communication and documentation may be tainted by poor or absent definitions. The stories and scenarios created to example requirements must obviously use the same terminology as the requirement so it is critical to gain agreement early on.

Identify your sources of definitions. These could be an agreed language dictionary, source texts (books, standards etc.) and a company glossary. The company glossary is likely to be incomplete or less precise than required. The purpose of the definitions activity is to identify the terms needing definition, to capture and agree terminology and to check that the language used in requirements and stories is consistent.

On first sight of a requirement text, underline the nouns and verbs and check that these refer to agreed terminology or that a definition of those terms is required.

• What do the nouns and verbs actually mean? Highlight the source of definitions used. Note where definitions are absent or conflict.
• Where a term is defined, ask stakeholders – is this the correct, agreed definition? Call these ‘verified terms’.
• Propose definitions where no known definition exists. Mark them as ‘not verified by the business’. Provide a list of unverified terms to your stakeholders for them to refine and agree.

When you start the process of creating a glossary, progress will be slow. But as terms are defined and agreed, progress will accelerate rapidly. A glossary can be viewed as a simple list of definitions, but it can be much more powerful than that. It’s really important to view the glossary as a way of making requirements both more consistent and compact – and not treat glossary maintenance as just an administrative chore.

• A definition can sometimes describe a complex business concept. Quite often in requirements documents, there is huge scope for misinterpretation of these concepts, and explanations of various facets of these concepts appear scattered throughout requirements documents. A good glossary makes for more compact requirements.
• Glossary entries don’t have to be ‘just’ definitions of terminology. In some circumstances, business rules can be codified and defined in the glossary. A simple business rule could be the validation rule for a piece of business data, for example a product code. But it could be something much more complex, such as the rule for processing invoices and posting entries into a sales ledger.

Glossary entries that describe business rules might refer to features identified in the requirements elsewhere. The glossary (and index of usage of glossary entries) can therefore provide a cross-reference of where a rule is used and associated system feature is used.

F – Features – One Story per Feature

Users and business analysts usually think and document requirements in terms of features. A feature is something the proposed system needs to do for its user and helps the user to meet a goal or supports a critical step towards that goal.

Features play an important part in how business users, wishing to achieve some goal, think. When visualising what they want of a system, they naturally think of features. Their thoughts traverse some kind of workflow where they use different features at each step in the workflow. ‘… I’ll use the search screen to find my book, then I’ll add it to the shopping cart and then I’ll confirm the order and pay’.

Each of the phrases, ‘search screen’, ‘shopping cart’, ‘confirm the order’ and ‘pay’ sound like different features. Each could be implemented as a page on a web site perhaps, and often features are eventually implemented as screen transactions. But features could also be processes that the system undertakes without human intervention or unseen by the user. Examples would be periodic reports, automated notifications sent via email, postings to ledgers triggered by, but not seen by, user activity. Features are often invoked by users in sequence, but features can also collaborate to achieve some higher goal.

When reading a requirement and looking for features, sometimes the features are not well defined. In this case, the best thing is to create a story summary for each and move on to the scenarios to see how the stories develop.

Things to look for:

• Named features – the users and analysts might have already decided what features they wish to see in the system. Examples could be ‘Order entry’, ‘Search Screen’, ‘Status Report’.
• Phrases like, ‘the system will {verb} {object}’. Common verbs are capture, add, update, delete, process, authorise and so on. Object could be any entity the system manages or processes for example, customer, order, product, person, invoice and so on. Features are often named after these verb-object phrases.
• Does the requirement describe a single large or complex feature or can distinct sub-features be identified? Obviously larger requirements are likely to have several features in scope.
• Are the features you identify the same features used in a different context or are they actually distinct? For example, a feature used to create addresses might be used in several places such as adding people, organisations and customers.

O – One Scenario per Outcome

More than anything else, a requirement should identify and describe outcomes. An outcome is the required behaviour of the system when one or more situations or scenarios are encountered. We identify each outcome by looking for requirements statements that usually have two positive forms:

• Active statements that suggest that, ‘…the system will…’
• Passive statements that suggest that ‘…valid values will …’ or ‘…invalid values will be rejected…’ and so on.

Active statements tend to focus on behaviours that process data, complete transactions successfully and have positive outcomes. Passive statements tend mostly to deal with data or state information in the system.

There is also a negative form of requirement. In this case, the requirement might state, ‘…the system will not…’. What will the system not do? Usually, these requirements refer to situations where the system will not accept or proceed with invalid data or where a feature or a behaviour is prohibited or turned off, either by the user or the state of some data. In almost every case, these ‘negative requirements’ can be transformed into positive requirements, for example, ‘not accept’ could be worded as ‘reject’ or possibly even as ‘do nothing’.

You might list the outcomes that you can identify and use that list as a starting point for scenarios. Obviously, each unique outcome must be triggered by a different scenario. You know that there must be at least one scenario per outcome.

There are several types of outcome, of which some are observable but some are not.

Outputs might refer to web pages being displayed, query results being shown or printed, messages being shown or hard copy reports being produced. Outputs refer to behaviour that is directly observable through the user interface and result in human-readable content that is visible or available on some storage format or media (disk files or paper printouts).

Outcomes often relate to changes of state of the system or data in it (for example, updates in a database). Often, these outcomes are not observable through the user interface but can be exposed by looking into the database or system logs perhaps. Sometimes outcomes are messages or commands sent to other features, sub-systems or systems across technical interfaces.

Often an outcome that is not observable is accompanied by a message or display that informs the user what has happened. Bear in mind, that it is possible that an outcome or output can be ‘nothing’. Literally nothing happens. A typical example here would be the system’s reaction to a hacking attempt or selection of a disabled menu option/feature.

Things to look out for:

• Words (usually verbs) associated with actions or consequences. Words like capture, update, add, delete, create, calculate, measure, count, save and so on.
• Words (verbs and nouns) associated with output, results or presentation of information. Words like print, display, message, warning, notify and advise.

S – Scenarios – One Scenario per Requirements Decision

We need to capture scenarios for each decision or combination of decisions that we can associate with a feature.

Often, the most common or main success scenario is described in detail and might be called the ‘main success’ or ‘default’ scenario. (In the context of use cases, the ‘main success scenario’ is the normal case. Variations to this are called extensions or scenarios). The main success scenarios might also be called the normal case, the straight-through or plain-vanilla scenario. Other scenarios can represent the exceptions and variations.

Scenarios might be split into those which the system deals with and processes, and those which the system rejects because of invalid or unacceptable data or particular circumstances that do not allow the feature to perform its normal function. These might be referred to as negative, error, input validation or exception condition cases.

The requirement might present the business or technical rules that govern the use of input or stored data or the state of some aspect of the system. For example, a rule might state that a numeric value must lie within a range of values to be treated as valid or invalid, or the way a value is treated depends on which band(s) of values it lies in. These generalised rules might refer to non-numeric items of data being classified in various ways that are treated differently.

A scenario might refer to an item of data being treated differently, depending on its value. A validation check of input data would fall into this category (different error messages might be given depending on the value, perhaps). But it might also refer to a set of input and stored data values in combination. A number of statements describing the different valid and invalid combinations might be stated in text or even presented in a decision-table.

Things to look out for:

• Phrases starting (or including) the words ‘if’, ‘or’, ‘when’, ‘else’, ‘either’, ‘alternatively’.
• Look for statements of choice where alternatives are set out.
• Where a scenario in the requirement describes numeric values and ranges, what scenarios (normal, extreme, edge and exceptional) should the feature be able to deal with?

P – Prediction

Each distinct scenario in a requirement setting out a situation that the feature must deal with, should also describe the required outcome associated with that scenario. The required outcome completes the definition of a scenario-behaviour statement. In some cases, the outcome is stated in the same sentence as the scenario. Sometimes a table of outcomes is presented, and the scenarios that trigger each outcome are presented in the same table.

A perfect requirement enables the reader to predict the behaviour of the system’s features in all circumstances. The rules defined in the requirements, because they generalise, should cover all of the circumstances (scenarios) that the feature must deal with. The outcome for each scenario will be predictable.

Now, of course, it is completely unrealistic to expect a requirement to predict the behaviour in all possible situations because most situations are either not applicable or apply to the system as a whole, rather than a single feature.

However, where scenarios are identifiable, the need must be to predict and associate an outcome with those scenarios.

When you consider the outcomes identified on the Outcomes stage, you might find it difficult to identify the conditions that cause them. Sometimes, outcomes are assumed or a default outcome may be stated but not associated with scenarios in the requirements text. These ‘hanging’ outcomes might be important but might never be implemented up by a developer. Unless, that is, you focus explicitly on finding these hanging outcomes.

Things to look out for:

• Are all outcomes for the scenarios you have identified predictable from the text?
• If you cannot predict an outcome try inventing your own outcomes – perhaps a realistic one and perhaps an absurd one and keep a note of these. The purpose of this is to force the stakeholder to make a choice and to provide clarification.

A – Ambiguity

The Definitions phase is intended to combat the use of ambiguous or undefined terminology. The other major area to be addressed is ambiguity in the language used to describe outcomes.

Ambiguity strikes in two places. Scenarios identified from different parts of the requirements appear to be identical but have different or undefined outcomes. Or two scenarios appear to have the same outcomes, but perhaps should have different outcomes to be sensible.

There are several possible anomalies to look out for:

• Different outcomes imply different scenarios but it appears you can obtain the same outcome with multiple scenarios. Is something missing from the requirement?
• It is possible to derive two different outcomes for the same scenario. The requirement is ambiguous.

In general, the easiest way to highlight these problems to stakeholders is to present the scenarios/outcome combinations as you see them and point out their inconsistency or duplication.

Look out for:

• Different scenarios that appear to have identical outcomes but where common sense says they should differ.
• Identical scenarios that have different outcomes.

M – Missing

If we have gone through all the previous steps and tabulated all of our glossary definitions, features, scenarios and corresponding outcomes we perform a simple set of checks as follows:

• Are all terms, in particular nouns and verbs defined in the glossary?
• Are there any features missing from our list that should be described in the requirements? For example, we have create, read and update features, but not delete feature
• Are there scenarios missing? We have some but not all combinations of conditions identified in our table
• Do we need more scenarios to adequately cover the functionality of a feature?
• Are outcomes for all of our scenarios present and correct?
• Are there any outcomes that are not on our list that we think should be?

Workshops

Story-driven requirement validation, being based on the DeFOSPAM checklist is easily managed in a workshop format in three phases. Requirements might be clustered or chunked into selected groups to be reviewed. It is helpful if all of the terms requiring definition, clarification or agreement are distributed ahead of the session, so the stakeholders responsible for the definitions can prepare ahead of the meeting.

At the workshop or review meeting, each requirement is considered in turn and the discussion of the stories derived from it is performed:

• Firstly, consider the definitions to be captured and agreed. The group need to consider the definition of every term individually but also in the context of other related terms as a self-consistent group.
• For each feature, the scenarios are considered one by one. Where there are suspected omissions, ambiguities, these are discussed and corrected as necessary.
• The scenarios for a feature are considered as a set: have enough scenarios been documented to understand the requirement? Do they provide enough spread? Do they cover the critical situations?
• The requirement, stories and scenarios are considered as a whole: is the requirement clear, complete and correct? Are all features identified and all requirements addressed or described by one or more stories? Can the requirements and stories be trusted to proceed to development?

Usually, discrepancies in requirements, definitions and stories can be resolved quickly in the meeting and agreed to.

The text of this post has been extracted from The Business Story Pocketbook written by Paul Gerrard and Susan Windsor.

Tags: #DeFOSPAM #businessstory #requirementsvalidation

Paul Gerrard My linkedin profile is here My Mastodon Account