APPENDIX 1
SCENARIO-BASED SYSTEM DEVELOPMENT TEMPLATES
Ian Alexander
This Appendix provides document templates for:
- Mission and Objectives
- Stakeholder Analysis
- Use Cases
- Non-Functional Requirements
- Test Cases
The templates may freely be copied and applied on projects, provided they are used as instructed, and provided that the copyright and source are acknowledged on each copy. They must not be sold or hired out.
The templates are believed to be suitable as a basis for simple projects, but they may need to be adapted for specialised projects and development approaches.
They are provided for free download at http://www.scenarioplus.org.uk
Appendix 1.1: Mission and Objectives Template
Ian Alexander
This document provides a standardised set of headings to document the top-level goals, often called the Project Mission and Objectives, in any style of project documentation.
Use of Copyright Material
This template may freely be copied and applied on projects, provided it is used as instructed, and provided that its copyright and source are acknowledged. It must not be sold or hired out.
1. Project Mission
1.1 Project Sponsor / Champion
Identify the person, probably in a position of power, who has openly stated that he/she intends to champion the project right through to completion. The sponsor / champion need not be involved in day-to-day management of the project, but must be determined that it shall succeed, be willing to fight for it when necessary, and have the ability to obtain the necessary resources (e.g. money, staff, test facilities, etc) to ensure its success. They must also be likely to stay in the organisation for the duration of the project.
The Project Sponsor / Champion is ……………….
(name, job title, department, contact details)
1.2 Mission Statement
Write a sentence defining the single central thing that the project, system, or product in question must accomplish. This is also the basic criterion as to whether the project has been successful.
For example,
“The mission of the RuriSportBike project is:”
“To become the market leader in sporting bicycles in Ruritania.”
The mission must be brief, clear, and realistic. It must be verifiable, that is, you would know if you had achieved it (e.g. you know have 31% of the Ruritanian bicycle market).
The mission of the … … … … … … … … project is:
To … … … … … … … … … … … … …
2. Business Objectives
Write one sentence for each business objective, that is, each key purpose of the project, system, or product in question. A high-level requirement is only an objective if it is a defining feature, that is, that a successful result could not exist without it. Only a few of a project's mandatory requirements are really central to its being.
It is allowed to have more than one objective, but if there are multiple objectives they must not conflict. However, there should not be too many objectives or focus will be lost.
For example,
“To develop an attractive sporting bicycle that we can produce locally.”
“To set up an effective bicycle production facility.”
“To set up an effective national bicycle sales & distribution network.”
Objectives must be brief, clear, and realistic (within the limits of budget, time, skill, geography and other relevant resources). Objectives must be verifiable, that is, it must be possible to know whether or not you have attained each objective.
Each objective should be owned by a named stakeholder, who will be responsible for achieving it within the framework of the project.
2.1 Objective 1
To … … … … … … …
Owner: … … … … … … … … … …..(name, contact details)
2.2 Objective 2
To … … … … … … …
Owner: … … … … … … … … … …..(name, contact details)
2.3 Objective 3
To … … … … … … …
Owner: … … … … … … … … … …..(name, contact details)
3. Initial SWOT Analysis
Briefly and honestly list the main factors that will affect the success of the project, under the following headings.
3.1 Strengths
List the factors favouring the project compared to its rivals, past projects, and so on.
3.2 Weakness Analysis
3.2.1 Weaknesses
List the internal factors such as shortage of funding, staff turnover, skill shortage, and so on, working against the project.
3.2.2 Remedies
State for each identified weakness how you intend to remedy the weakness so that the project can succeed. Remedies must be realistic, that is, they must be capable of resolving the problems and they must be achievable within the resources of the project.
3.3 Opportunities
List the external factors such as the state of the market that would be beneficial if the project were to succeed.
3.4 Threat Analysis
3.4.1 Threats
List the external factors such as changing technology, rivals, internal opposition, and so on, that could threaten the success of the project.
3.4.2 Mitigations
State for each identified threat how you intend to mitigate or prevent the threat from causing harm. Mitigations must be realistic, that is, they must be capable of neutralising the threats and they must be achievable within the budget, timescale, skill and the other actual resources to hand.
Appendix 1.2: A Stakeholder Template
Ian Alexander
1. Project Stakeholders
This document provides a standardised set of headings for use when analysing stakeholders in any style of project documentation. This first section illustrates the structure and gives an example of its use. The second section offers some guidelines. The third section is the template.
1.1 Example ‘Onion-Rings’ Stakeholder Diagram
A Typical Set of Stakeholder Roles
The Onion-Rings Diagram offers a simple way of visualising a set of stakeholder roles on a project. A free tool to create and manage onion diagrams and associated stakeholder information in the DOORS requirements tool environment is available from http://www.scenarioplus.org.uk
The centre is always the equipment (‘kit’, ‘product’) in question.
The system or ‘work’ is always larger than the equipment—in particular, it includes the people who play operational roles, such as the pilots and fitters who carry out normal and maintenance operations on an aircraft. Systems also normally include operational procedures, training manuals and other information as well as the equipment.
Many systems also include maintenance and training kit, such as simulators and automated test equipment, and it is important to determine whether these are inside or outside the work boundary.
Outside the work boundary lie the direct beneficiaries of the work. These include those who immediately benefit from the functions carried out by the system (including the operators and the kit). Usually these beneficiaries are different from the operators, but sometimes these roles can be combined, as with home entertainment products such as music players where the operator is also often the person benefiting from using the product.
Further out still are people who are affected indirectly, either deriving benefits such as political gains or financial rewards (e.g. through shareholdings), or suffering harm (having negative stakes) such as the impact of noise, pollution, electromagnetic radiation, loss of amenity, or loss of work.
Roles often involve an element of surrogacy. For example,
- Regulators are typically appointed by government or industry to act as informed surrogates for the public. For example, a health and safety authority monitors and controls industry to ensure practice conforms to standards, and hence minimises risk to both operators and the public. As another example, the international radio regulator creates a framework of rules and assigns radio frequencies to different purposes, so as to minimise electromagnetic interference.
- Purchasing / procurement is generally carried out by a department distinct from operations, and essentially on behalf of both operational and beneficiary roles, whether or not those roles exist at the time the procurement is made.
Surrogate opinions are important, but they are not necessarily equivalent to the views of the people they claim to represent. For instance, it is dangerous for requirements engineers to assume that the viewpoint of a manager corresponds to those of the people—for example maintenance operators—being managed.
A Simple Classification of Stakeholder Roles
1.2 An Extensible Hierarchy
The purpose of this approach to stakeholder analysis is to help projects pay more effective attention to the roles and viewpoints involved. All domains are different, but some features of stakeholder structure are essentially similar everywhere.
This hierarchy is meant to be extended on specific projects and in specific domains, by splitting (i.e. specialising) the categories to make them easy to understand and to apply.
For example, in the Railway domain, Normal Operators include Train Driver, Line Controller, Station Controller (depending on the specific system you are considering), while Maintenance Operator in general means Asset Maintainer, which can be specialised into Train Maintainer, Track Maintainer, Lift/Escalator Maintainer, and so on.
2. Guidelines
2.1 Stakeholder Analysis
Fill in the template for your project, using it as a set of general hints to help you discover the key roles and individuals playing those roles. Add table rows for additional stakeholders. Document stakeholders' actual names and their personal viewpoints on the project; if need be, document their roles in more detail, and record their job titles, departments and other clues to their involvement on the project.
Pay special attention to anomalies:
- if any positive role is filled by more than one stakeholder or group of stakeholders, there may be conflicting viewpoints on your project. Take care to discover the different viewpoints, and plan for conflict resolution workshops or other preventative measures. For example, if the Purchasing role is split (procurement is split across more than one agency) then you must ensure there will not be constant debate on acceptance criteria, and so on.
- if any role is unfilled on your project, there may be hidden requirements that will not be discovered until late in the project.
- if people are reluctant to discuss an area, this may be because it is known to be dangerous within the organisation. Take care to understand the cause, and find out what kinds of risk it poses to your project.
- if some people say a role is important and some say it is not, this is always significant. Acknowledge the different viewpoints, remain neutral, and make clear that you are collecting viewpoints from all affected stakeholders.
If you find the template does not exactly match the needs of your project—as is likely—then add roles or otherwise modify the template to reflect reality more accurately.
2.2 Tool Support
The template can be used directly to analyse stakeholder roles and viewpoints using only a word processing tool, and this immediately provides benefit through increased clarity and reduced risk to the project.
However, where there are many requirements, frequent changes, large or distributed teams, and long projects, word processing alone is not sufficient to manage all the project information, and especially not the traces or links between items such as goals, viewpoints, requirements, and tests essential to ensure that stakeholders get what they need.
Such projects should select a requirements management tool (such as DOORS, Slate, Cradle, Requisite Pro, etc) to enable project engineers to create, maintain, and receive the benefit of a complete and consistent view of project information.
2.3 Use of Copyright Material
This template may freely be copied and applied on projects, provided it is used as instructed, and provided that its copyright and source are acknowledged. It must not be sold or hired out.
3. Stakeholder Roles
3.1 Beneficiary
3.1.1 Functional Beneficiary
| Stakeholder: | Viewpoint: |
| John Smith | wants to see accurate weekly and monthly sales figures and forecasts |
3.1.2 Financial Beneficiary
| Stakeholder: | Viewpoint: |
3.1.3 Political Beneficiary
| Stakeholder: | Viewpoint: |
3.1.4 Purchasing
| Stakeholder: | Viewpoint: |
3.2 Negative
| Stakeholder: | Viewpoint: |
3.3 Regulatory
3.3.1 Voluntary (Standardising)
| Stakeholder: | Viewpoint: |
3.3.2 Enforcing
| Stakeholder: | Viewpoint: |
3.4 Operational Roles
3.4.1 Human Operators
3.4.1.1 Normal
| Stakeholder: | Viewpoint: |
3.4.1.2 Maintenance
| Stakeholder: | Viewpoint: |
3.4.2 Neighbouring Systems
| Stakeholder: | Viewpoint: |
3.5 Expert
3.5.1 Safety Opinion
| Stakeholder: | Viewpoint: |
3.5.2 Usability Opinion
| Stakeholder: | Viewpoint: |
3.5.3 Domain Knowledge (divide this into sub-domains if appropriate)
| Stakeholder: | Viewpoint: |
3.5.4 Implementability
3.5.4.1 Software Opinion
| Stakeholder: | Viewpoint: |
3.5.4.2 Hardware Opinion
| Stakeholder: | Viewpoint: |
Appendix 1.3: Use Case Templates
Ian Alexander
This appendix is a set of templates for different styles of Use Case. Similar templates can be generated automatically by Scenario Plus (http://www.scenarioplus.org.uk) in a DOORS environment; online versions of the templates are provided in a range of file formats on the Scenario Plus website for free downloading. The templates can be used in essentially any software tool that provides document, spreadsheet, or database like facilities. Paradoxically the most limiting tools for the purpose are those mainly graphical tools that are intended for editing use case and other software specification models.
The values that each attribute can take in columns 4 to 7 are listed in the Introduction. Values are expected only once per Use Case.
Use of Copyright Material
This template may freely be copied and applied on projects, provided it is used as instructed, and provided that its copyright and source are acknowledged. It must not be sold or hired out.
Appendix 1.4: Non-Functional Requirements Template
Introduction
Non-Functional Requirements Template
This template is a hierarchy of headings that we find helpfully suggestive of questions to ask our clients when putting specifications together, annotated with suggestions as to how each category of Non-Functional Requirements (NFRs) may be verified—for many NFRs are difficult to test, and testing is often an inappropriate verification approach for them.
You will certainly need to customise both the list of NFRs and the associated Verification Approach to suit your kind of system. However, it may be a useful antidote to software-only thinking: even software houses have to ensure their computers and networks have compatible connectors.
The Verification Approach in particular must be thought through for each specific project as the effort necessary is a function of the criticality of the system to your business, whether safety is involved, and not least the particular characteristics of your domain. The suggestions are meant to be generally applicable but this cannot be guaranteed.
For many engineering systems, the NFRs form a much larger part of the specifications than the behaviour (functions and performance) does. Once you have customised the template you will find that it saves you a lot of effort when you start a project.
Acknowledgements
This template was originally developed for project use in discussions with Andrew Farncombe. It has been revised in the light of work done by Don Firesmith at the SEI, and of course it is part of a wider body of work to make NFRs more tractable by INCOSE, the RESG and others.
Use of Copyright Material
This template may freely be copied and applied on projects, provided it is used as instructed, and provided that its copyright and source are acknowledged. It must not be sold or hired out.
Appendix 1.5: Test Case Templates
Ian Alexander
This is a set of templates for a range of common kinds of test case, based rather directly on use cases (see Appendix 1-3 Use Case Templates).
They are simple, frequently occurring patterns or idioms in scenario-based systems engineering. They are not all necessarily required on all projects, but it is likely that most projects will need to use most of them.
In the (simple) view taken here, test cases are purely sequential, straight-line scenarios. It is true that some software test tools, for example, can automatically navigate a tree structure and test all the paths it defines. But firstly, doing so is equivalent to running a set of simple sequential test cases; and secondly, the automated rules for navigating such a tree need to cater for the test case patterns described here, because sometimes you need to do things twice to be reasonably sure the system is working properly. (Issues of concurrency and non-determinism due to multi-threading are another matter entirely.)
The test case structures can act as hints as to the kinds of test that you should be constructing, based on the pattern of use cases that you have in your projects. They effectively ask you certain questions about the completeness of your verification approach, such as ‘do you know whether such-and-such a function would be restored after a reset?’
Use of Copyright Material
This set of templates may freely be copied and applied on projects, provided it is used as instructed, and provided that its copyright and source are acknowledged. It must not be sold or hired out.
1. Functional / Performance Tests
For each Use Case:
- a) Set up the required preconditions
(Note: this may mean creating a set of similar tests, varying one environmental condition e.g. temperature, vibration, or humidity at a time.)
- b) Set up any needed performance monitoring equipment
- c) Run the entire normal course / ‘happy day’ scenario
- d) Check that the expected normal result is obtained
- e) Check that the performance target is met.
2. Stress Tests
For each Use Case that can be run as a transaction (or group of such Use Cases that can form a mix of transactions) to be performed many times / in parallel within the system:
- a) Set up the required preconditions
- b) Set up any needed performance monitoring equipment
- c) Set up any needed stress-load simulator / equipment
- d) Run the entire normal course / ‘happy day’ scenario as many times / in parallel as required to stress the system
- e) Check that the stress target is met.
3. Stopping Tests (for Faults, Security Threats, Safety Hazards)
For each System Fault, Security Threat or Misuse Case, or Safety-related Hazard corresponding to an Exception Event which should cause the system to Stop safely:
- a) Set up the required preconditions
- b) Set up the required test equipment, simulator, fault injector, and so on
- c) Run the normal course / ‘happy day’ scenario starting from its beginning
- d) Inject the threatened event / fault condition (or simulate it)
- e) Check that the correct Exception-handling scenario is executed
- f) Check that the system stops safely.
If appropriate:
- g) Reset the system manually in accordance with standard operating procedure
- h) Run the entire normal course / ‘happy day’ scenario again
- i) Check that the normal result is obtained.
4. Recovery Tests (for Faults, Security Threats, Safety Hazards)
For each System Fault, Security Threat or Misuse Case, or Safety-related Hazard corresponding to an Exception Event from which the system is expected to Recover:
- a) Set up the required preconditions
- b) Set up the required test equipment, simulator, fault injector, and so on
- c) Run the normal course / ‘happy day’ scenario starting from its beginning
- d) Inject the threatened event / fault condition (or simulate it)
- e) Check that the correct Exception-handling scenario is executed
- f) Run the rest of the normal course to completion
- g) Check that the normal result is obtained
- h) Run the entire normal course / ‘happy day’ scenario again
- i) Check that the normal result is again obtained.