Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Specification and Documentation TechniquesCS/SE 3RA3
Ryszard Janicki
Department of Computing and Software, McMaster University, Hamilton,Ontario, Canada
Ryszard Janicki Specification and Documentation Techniques 1/23
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Requirements evaluation
Inconsistency management
Risk analysis: types of risk, risk management, DDP process
Evaluating alternative options for decision making
Requirements prioritization: pairwise comparisons
Ryszard Janicki Specification and Documentation Techniques 2/23
Requirements specification and documentation
alternative options
Elicitationtechniques
Evaluationtechniques
start agreedrequirements
consolidatedrequirements requirementsrequirements
Specification &Specification &documentationdocumentationtechniquestechniques
documented requirements
techniquestechniques
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural languageFree documentation in unrestricted natural language
Requirements specification and documentation : outline
1 Free documentation in unrestricted natural language2 Disciplined documentation in structured natural
languageLocal rules on writing statementsGlobal rules on organizing the Requirements Document
3 Standards (i.e. standardized disciplined documentationin structured natural language)
4 Fit Criteria
5 Use of graphical (called ‘diagrammatic’ in the textbook)notations
6 Formal specification
Natural language is the basic tool for points 1-4
Ryszard Janicki Specification and Documentation Techniques 4/23
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural languageFree documentation in unrestricted natural language
Free documentation in unrestricted natural language
Unlimited expressiveness communicability no training needed Unlimited expressiveness, communicability, no training needed Prone to many of the spec errors & flaws
Ambiguities are inherent to natural language; can be harmful“Full braking shall be activated by any train that receives anoutdated acceleration command or that enters a station blockat speed higher than X km/h, and for which the precedingtrain is closer than Y meters.”
Frequent confusions among logical connectives in naturallanguage- e.g. case analysis:
If Case1 then <Statement1> or If Case2 then <Statement2>vs
If Case1 then <Statement1> and If Case2 then <Statement2>
Ryszard Janicki Specification and Documentation Techniques 5/23
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
Stylistic rules for good structured natural languagespecification: a sample
Identify who will read this; write accordingly
Say what you are going to do before doing it
Motivate first, summarize after
Make sure every concept is defined before use
Keep asking yourself: “Is this comprehensible? Is this enough?Is this relevant?”
Never more than one requirement, assumption, or domainproperty in a single sentence. Keep sentences short.
Use “shall” for mandatory, “should” for desirable prescriptions
Avoid unnecessary jargon and acronyms
Use suggestive examples to clarify abstract statements
Supply diagrams for complex relationships among item
Ryszard Janicki Specification and Documentation Techniques 6/23
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
Decision Tables: used for complex combinations ofconditions
Systematic and simpleAdditional benefits:
Completeness check: 2N columns required for full tableTable reduction: drop impossible cases in view of domainproperties; merge 2 columns differing only by single “T”, byreplacing it with “-” which means “T or F”Test cases for free (cause-effect coverage)
Ryszard Janicki Specification and Documentation Techniques 7/23
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
Standardized statement templates
Identifier –suggestive; hierarchical if compound statement
Category –functional or quality req, assumption, domainproperty, definition, scenario example, ...
Specification –statement formulation according to stylisticrules
Fit criterion –for measurability
Source –for traceability to elicitation sources
Rationale –for better understanding and traceability
Interaction –contribution to, conflict with other statements
Priority level –for comparison and prioritization
Stability, Commonality levels –for change management
Fit criterion is a measure of specification.
Ryszard Janicki Specification and Documentation Techniques 8/23
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
Specifications vs Fit Criteria
Fit criteria make statements measurable
Complement statements by quantifying the extent to whichthey must be satisfied
Especially important for measurability of Non-FunctionalRequirements
Specification: The scheduled meeting dates shall be convenient toparticipantsFit criterion: Scheduled dates should fit the diary constraints ofat least 90% of invited participants in at least 80% of casesSpecification: Information displays inside trains shall beinformative and understandableFit criterion: A survey after 3 months of use should reveal that atleast 75% of travelers found in-train info displays helpful for findingtheir connection
Ryszard Janicki Specification and Documentation Techniques 9/23
Example (Elevator System: Specifications vs Fit Criteria)
Specification 1 -The doors shall open and close gradually toallow people to easily enter and exit the car.Fit Criterion - 90% of time the time (when the lift car is atground floor) the door shall not take more than 2 seconds tocompletely open. Otherwise on any other floor door can take2-3 seconds to open
Specification 2 - If the system fails due to heavy load that ismore than 1587 kgs, the users should not be put in anydanger.Fit Criterion - The user using the lift should be alerted andthen feedback sound should be given to the user indicatingthe amount of users to be dismounted from the elevator.
Specification 3 - The system should implement an algorithmto minimize average wait times.Fit Criterion - The system should implement an algorithm tominimize wait times in such a way that average wait time foran elevator will not exceed 60 seconds.
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
IEEE Std-830, Volere
IEEE Std-830 template for organizing the RequirementDocument. See ‘Requirements Specification in IEEE830’ and‘Solutions for assignment 2 from 2014 on the course website.
Volere template: has explicit sections for domain properties,costs, risks, development workplan, etc. See ‘Volere-Template’and Elevator in Volere Pattern’ on the course website.
For engineering type systems IEEE standard is in most casespreferable, for purely management type systems Volere mightbe more convenient, but it has to be decided case by case.
Mixing IEEE Std-830 and Volere is allowed and often evenrecommended. For example Volere taxonomy ofnon-functional requirements is often used within IEEE Std-830standard.
Ryszard Janicki Specification and Documentation Techniques 11/23
IEEE Std-830
IEEE Std-830 template for organizing the RD
1. Introduction1.1 RD purpose
l f
domain, scope, purposeof system-to-be
1.2 Product scope1.3 Definitions, acronyms, abbreviations1 4 References
glossary of terms
elicitation sources1.4 References1.5 Overview
2. General Description2 1 P d t ti
sw-environment boundary:interfaces with users, devices other sw2.1 Product perspective
2.2 Product functions2.3 User characteristics
devices, other swfunctionalities of software-to-be
assumptions about users
2.4 General constraints2.5 Assumptions & Dependencies2 6 Apportioning of requirements
development constraints(hw limitations, implem platform, ...)environment assumptions2.6 Apportioning of requirements
3. Specific Requirementsp
(subject to change)optional, deferable reqs
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
IEEE Std-830
IEEE Std-830 template for organizing the RD (2)
3.3. Specific RequirementsSpecific Requirements3.1 Functional requirements
NFR i bili
alternative templates for alternative templates for specific types of systemspecific types of system
q3.2 External interface reqs3.3 Performance reqs
NFRs: interoperability
NFRs: time/space performance
3.4 Design constraints3.5 Software quality attributes
NFRs: development reqs
NFRs: quality reqs3.6 Other requirements
AppendicesIndex
NFRs: security, reliability, maintainability
Index
Ryszard Janicki Specification and Documentation Techniques 13/23
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
Example (Elevator in IEEE Std-830: Samples)
1. Introduction1.1 Purpose:
The purpose of this software requirement specificationdocument is to provide a complete description of therequirements in order to design controller software of anelevator system for a hotel.The intended audience of this document is all of thestakeholders for a project involving the development of elevatorcontroller software. This includes the software developmentteam and the hotel owner, the hotel’s architect, the hotel’srestaurant’s manager, the front desk, the hotel staff, and thehotel’s elevator technician.
Ryszard Janicki Specification and Documentation Techniques 14/23
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
Example (Elevator in IEEE Std-830: Samples)
1. Introduction1.2 Scope:
This elevator system is meant to be deployed in the hotel. Thecontrolling software that is specified within this document isresponsible for controlling the elevator’s movement betweenfloors. This document entails the specification of the softwareonly. The software is not responsible for any of the elevator’sphysical mechanisms and therefore any requirements relatingto said mechanisms are not included in this document.The goal of creating this software is to make an elevatorsystem that is fully operational for use in the hotel. This wouldmake traveling from different floors much faster and muchmore convenient.
Ryszard Janicki Specification and Documentation Techniques 15/23
Example (Elevator in IEEE Std-830: Samples)
1. Introduction1.3 Definitions, Acronyms, and Abbreviations:
These definitions will be used throughout the requirements andthe rest of the document.
Call button: This refers to either the ”up” or ”down” buttonsa person presses to call the elevator to a floor.Stop button: This refers to the set of buttons located insidethe elevator that are pressed to indicate that a person wouldlike the elevator to stop and open its doors on a floor.Requested floor: Refers to a floor for which the elevator hasbeen requested to stop at.Up request: Refers to when a request is made to move to afloor higher than the elevator currently is (This could be viacall button or stop button)Down request: Refers to when a request is made to move toa floor lower than the elevator currently is (This could be viacall button or stop button)Floor stop: Refers to the elevator stopping and opening itsdoors once when it arrives at a requested floor.
This is only a sample, more on the course website.
Example (Elevator in IEEE Std-830: Samples)
2. Overall Description2.1 Product Perspective:
The controller software specified in this Software RequirementsSpec is a part of a larger system - the elevator system. Thesoftware therefore must be able to interface with the elevatorsystem’s physical mechanisms such as the buttons, the sitemanager’s console, the floor displays, and the elevator display.
2.2 Product Functions:This subsections contains a description of the main functionsthe controller software must have.
a) Control Doors: The controller software decides where andwhen the elevator closes and opens its doors.
b) Control Movement: The controller software is able todetermine how the elevator moves. The software must be ableto monitor and influence the speed, acceleration, and directionof movement. The controller is able to determine where theelevator’s destination in response to request and/or floorbuttons being pressed.
This is only a sample, more on the course website.
Example (Elevator in IEEE Std-830: Samples)
3. Specific Requirements3.1 Product Perspective:
The controller software specified in this Software RequirementsSpec is a part of a larger system - the elevator system. Thesoftware therefore must be able to interface with the elevatorsystem’s physical mechanisms such as the buttons, the sitemanager’s console, the floor displays, and the elevator display.
3.2 Functional Requirements:This subsections contains a description of the main functionsthe controller software must have.
1. The elevator will make a floor stop if a call button is pressedon said floor. The elevator will make this floor stop at therequested floor in 17 floor stops or less. The elevator willmake a floor stop if a stop button is pressed for a certain floorin 17 stops or less provided that the passenger pressed a stopbutton that causes the elevator to travel in the direction theyindicated when they pressed the call button, that is, if theymade an up request with the call button they select a higherfloor when they press the stop button...............................
3. If the elevator door is open and the close door button ispressed, the elevator will make an attempt to close its doorsafter 3 seconds.
This is only a sample, more on the course website.
Volere (‘want’ in English) Template
Copyright © the Atlantic Systems Guild Limited Volere Template /2
Contents
Project Drivers 1. The Purpose of the Project 2. The Client, the Customer, and Other Stakeholders 3. Users of the Product
Project Constraints 4. Mandated Constraints 5. Naming Conventions and Definitions 6. Relevant Facts and Assumptions
Functional Requirements 7. The Scope of the Work 8. The Scope of the Product 9. Functional and Data Requirements
Nonfunctional Requirements 10. Look and Feel Requirements 11. Usability and Humanity Requirements 12. Performance Requirements 13. Operational and Environmental Requirements 14. Maintainability and Support Requirements 15. Security Requirements 16. Cultural and Political Requirements 17. Legal Requirements
Project Issues 18. Open Issues 19. Off-the-Shelf Solutions 20. New Problems 21. Tasks 22. Migration to the New Product 23. Risks 24. Costs 25. User Documentation and Training 26. Waiting Room 27. Ideas for Solutions
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
Volere Template
Copyright © the Atlantic Systems Guild Limited Volere Template /2
Contents
Project Drivers 1. The Purpose of the Project 2. The Client, the Customer, and Other Stakeholders 3. Users of the Product
Project Constraints 4. Mandated Constraints 5. Naming Conventions and Definitions 6. Relevant Facts and Assumptions
Functional Requirements 7. The Scope of the Work 8. The Scope of the Product 9. Functional and Data Requirements
Nonfunctional Requirements 10. Look and Feel Requirements 11. Usability and Humanity Requirements 12. Performance Requirements 13. Operational and Environmental Requirements 14. Maintainability and Support Requirements 15. Security Requirements 16. Cultural and Political Requirements 17. Legal Requirements
Project Issues 18. Open Issues 19. Off-the-Shelf Solutions 20. New Problems 21. Tasks 22. Migration to the New Product 23. Risks 24. Costs 25. User Documentation and Training 26. Waiting Room 27. Ideas for Solutions
Ryszard Janicki Specification and Documentation Techniques 20/23
Previous Few LecturesRequirements specification and documentation
Disciplined documentation in structured natural language
Stylistic RulesFit criteriaStandards
Volere Template
Copyright © the Atlantic Systems Guild Limited Volere Template /2
Contents
Project Drivers 1. The Purpose of the Project 2. The Client, the Customer, and Other Stakeholders 3. Users of the Product
Project Constraints 4. Mandated Constraints 5. Naming Conventions and Definitions 6. Relevant Facts and Assumptions
Functional Requirements 7. The Scope of the Work 8. The Scope of the Product 9. Functional and Data Requirements
Nonfunctional Requirements 10. Look and Feel Requirements 11. Usability and Humanity Requirements 12. Performance Requirements 13. Operational and Environmental Requirements 14. Maintainability and Support Requirements 15. Security Requirements 16. Cultural and Political Requirements 17. Legal Requirements
Project Issues 18. Open Issues 19. Off-the-Shelf Solutions 20. New Problems 21. Tasks 22. Migration to the New Product 23. Risks 24. Costs 25. User Documentation and Training 26. Waiting Room 27. Ideas for Solutions
Ryszard Janicki Specification and Documentation Techniques 21/23
Example (Elevator in Volere Pattern: Samples)Project Drivers
1. The Purpose of the Project a. The User Business or Background of the Project Effort
Skyhi Lifts manufactures elevators. The company requires a software-
based controller to control these elevators.
b. Goals of the Project
The goal of the project is to develop a software based controller.
2. The Client, the Customer and other Stakeholders
a. The Client
Skyhi Lifts
b. The Customer
Real state developers
c. Other Stakeholders
1. Business Analysts
2. Usability Experts 3. Legal Experts
4. Developers and Testers 5. Hardware Vendors
6. Others
3. Users of the Product
a. The Hands-On Users of the Product
- Through s e n s o r s and buttons general public will be using the
product. As the product is embedded software and certain rule
is programmed to run, there is no direct interaction with
human. Here t h e u s e r s are the sensors, motor and buttons.
- Maintenance and Service Technicians – needs to change the
setup through some interface which is not specified. Missing
requirement.
b. Priorities Assigned to Users
Key Users: Sensors, motor and buttons.
Secondary Users: Maintenance and Service Technicians
c. User Participation
Example (Elevator in Volere Pattern: Samples)
Project Drivers
1. The Purpose of the Project a. The User Business or Background of the Project Effort
Skyhi Lifts manufactures elevators. The company requires a software-
based controller to control these elevators.
b. Goals of the Project
The goal of the project is to develop a software based controller.
2. The Client, the Customer and other Stakeholders
a. The Client
Skyhi Lifts
b. The Customer
Real state developers
c. Other Stakeholders
1. Business Analysts
2. Usability Experts 3. Legal Experts
4. Developers and Testers 5. Hardware Vendors
6. Others
3. Users of the Product
a. The Hands-On Users of the Product
- Through s e n s o r s and buttons general public will be using the
product. As the product is embedded software and certain rule
is programmed to run, there is no direct interaction with
human. Here t h e u s e r s are the sensors, motor and buttons.
- Maintenance and Service Technicians – needs to change the
setup through some interface which is not specified. Missing
requirement.
b. Priorities Assigned to Users
Key Users: Sensors, motor and buttons.
Secondary Users: Maintenance and Service Technicians
c. User Participation
Not applicable.
d. Maintenance Users and Service Technicians
In order to service elevators the maintenance users a n d
service technicians requires the product to have s o me features in this
regard. So, there are some missing requirements which are to be listed
under non- functional requirements.
Project Constraints
4. Mandated Constraints a. Solution Constraints Software and hardware take control over the product. Mechanism is and structure will be provided by the client.
b. Implementation Environment of the Current System
Max 4 lifts per controller, max of 20 floors, one lift per shaft and all the lifts
have the same number of floors.
c. Partner or Collaborative Applications
Door Controller
d. Off-the-Shelf Software
Not applicable.
e. Anticipated Workplace Environment
- embedded software
f. Schedule Constraints
All requirements identified, must be implemented within stated deadline.
g. Budget Constraints
Not applicable.
5. Naming Conventions and Definitions
a. Definitions of all Terms
This is only a sample, more on the course website.