Requirements Documentation CSCI 5801: Software Engineering

Requirement Documentation

Unambiguous – Developers and clients have same understanding of what system must do Understandable – Simple enough for clients to understand – Detailed enough for you to create system based on it

Definition vs. Specification Requirements definition – Stated from the viewpoint of somebody outside the system (external viewpoint) – The system is a black box with some interface – The emphasis is on the role of the system Example: “The sprinkler never runs on rainy days”

Definition vs. Specification Requirements specification – Stated from the viewpoint of somebody inside the system – The environment is accessed via inputs & outputs – The emphasis is on how the system works Example: “The controller will not engage the water pump any time the ambient water sensor is triggered.”

Definition vs. Specification Requirements documentation may contain both – Definition: best for customers – Specification best for developers Understand difference If use both, make sure they agree

Scenarios Real-life examples of how system used – Single type of action taken by user and how system responds (like user story in XP) – “Atomic” form of functional requirements Should include: – A description of the starting situation – A description of the normal flow of events – A description of what can go wrong – A description of the state when the scenario finishes

Common Scenario Components A unique name and simple one-sentence description An initial assumption – Preconditions that must be true at start of scenario A description of the normal steps – What user does and what system does in response A list of exceptions – What could go wrong, and what system must do System state upon completion of the scenario Other simultaneous activities that could affect system Any nonfunctional requirements

Example Scenario “Fred wants to add CSIS He looks up the course on the system to get available sections. He likes the one at MWF 10 and selects it. His ID is added to the course roster”. What does student have to do before this? How can student look up sections? What if no open sections? What is student does not like any of the open sections? What can the student do next? How does this relate to what other students are doing?

Example Scenario Add Scenario Description: A student adds a course by entering a course number and selecting a section. Initial Assumption: Student has logged in and navigated to ADD screen, and has selected a course to add.

Example Scenario Normal Steps: System populates dropdown list of courses. Student selects a course from the list. A drop down with open sections (including their times) is populated. The student selects one and presses ADD. The student is added to the course roster. An acknowledgement of the add is displayed. The student may add more courses, or exit to the main menu.

Example Scenario Exceptions: All sections of the selected course may be closed, in which case a message is popped up instead of the drop down being populated. The student may not like any of the open sections, in which case they can either enter another course or press CANCEL to return to the main menu. The course may be closed before the student presses ADD, due to other students adding, in which case a message is displayed and the list of open sections displayed again.

Example Scenario System State upon Completion: The student ID is added to the roster of the section chosen. If that was the last remaining seat, the section is now closed. Simultaneous activities: Up to 500 other students may be adding and dropping courses. This might result in courses closing while the student is in the process of adding this one. It might also affect response time.

Example Scenario Nonfunctional Requirements: On average a student who has registered for one semester previously should make no more than 3 mistakes during an entire session and should be able to add all of their courses within 15 minutes. For requests for open sections, the system response time should be less than 2 seconds in 90% of cases under normal load.

Unified Modeling Language (UML)

Graphical representations for design/analysis – How we tend to do design Common design specification language – Experienced developer should be able to immediately understand system from diagram – Simple enough for customer to understand – Well-defined enough to allow developers to create system

Unified Modeling Language (UML) Based on earlier graphical representations – Entity Relationship diagrams (from database design) – Finite state machines – Data flow diagrams Controlled by OMG (Object Management Group) consortium – Latest version: UML 2 UML 2 has 13 diagram types – Often loose semantics – Some types used more than others

Use Case Diagrams Define major roles of entities in system – Usually in terms of user activities – Actors that interact with system for that activity

Registration Use Cases

Use Case Refinement Can show overall use case as sequence of other use cases

Use Case Refinement Can extend general use case to more specific ones

Sequence Diagrams Define role of each object in overall use case – Each object has “lifeline” – Describe information passed/returned – May show options for multiple scenarios in same use case – Also used at design to show information flow inside system

Sequence Diagram

Mathematical Specifications The deceleration of the train shall be computed as: – D train = D control + D gradient where D gradient is 9.81ms 2 * compensated gradient/alpha and where the values of 9.81ms 2 /alpha are known for different types of train.

Tabular Specification

IEEE requirements standard Defines a generic structure for a requirements – Introduction. General background and purpose of system – General description Requirements described at customer level – Specific requirements. Requirements described at developer level – Appendices. – Index.

IEEE Standard Introduction 1.1. Purpose 1.2. Scope 1.3. Definitions, acronyms and abbreviations 1.4. References 1.5. Overview 27 Based on feasibility study Glossary of possibly ambiguous terms CRN, course number, advisor, etc. Sources of requirements (interviews, recordings, forms, etc.)

IEEE Standard General description 2.1. Product perspective 2.2. Product functions 2.3. User characteristics 2.4. Constraints 2.5. Assumptions and dependencies 28 Hardware and software system will run on List of features system will have (written at customer level) Description of users of system, including knowledge of domain and experience with computing

IEEE Standard Specific requirements 3.1. External interface requirements User interfaces Hardware interfaces Software interfaces Comm. interfaces 29 General description of user interfaces, including layouts common to all scenarios, and general UI functional requirements such as training time Descriptions of hardware (such as sensors), legacy software, and networks the system must work with

IEEE Standard Functional requirements User class Functional req Functional req User class 2 … 30 Detailed description of individual use cases in whatever form appropriate (scenarios, sequence diagrams, etc.)

IEEE Standard Performance requirements 3.4. Design constraints 3.5. Software system attributes 3.6. Other requirements SE, Requirements Engineering, Hans van Vliet, © General non-functional requirements not directly related to any specific scenario, such as overall performance, general reliability, sustainability, etc.