2017-Spring CS350

Project #02: Software Requirements Specification (SRS)

Review/Feedback

SELab, KAIST

Main Scoring Criteria

• Completeness• Functional & non-functional requirements• Use cases• Main flow of use case description• Sequence diagram

• Consistency• Use case diagram & use case description• Use case diagram & sequence diagram

• Understanding of basic skills of modeling• Use case diagram• Use case description• Domain model (using a class diagram)

Feedback on Project#2

Vision Statement & Roadmap

• Vision statement should include a quick description about:• The overall goal of the system development• A strategy or strategies to lead your team to success• The top-level requirements associated with the system goal

• By providing a product roadmap, stakeholders could see a high-level view of the product requirements, with a loos time frame for when you will develop those requirements.

• Roadmap should identify & list the high-level product requirements• For the agile process, the identified requirements should be prioritized based

on the roughly estimated effort for each requirement.• In other words, articulating/providing the product roadmap is same as

providing a vision to your stakeholders.• What the designers/developers will design/implement

• How much effort is needed for each task

• What requirements have higher priority from project manager’s point of view(The priorities can be different from stakeholders’)

• When the intermediate and final product will be delivered

Definition of Functional Requirements

• Each functional requirement should be written unambiguously.• Many teams wrote the sentences without considering “ambiguity”• Please read every sentence with checking if there is any ambiguous terms in

functions, data, actors, and so on.

• Each functional requirement should be related to a specific actor(s) who participate(s) in performing the function.

• Some teams did not specify specific actors in their functional requirements.• Identifying actors is one of the essential activities in the requirements

specification process.

• A functional requirement can contain multiple sub-requirements. You can represent those requirements hierarchically if needed.

• Every requirement can fail to execute successfully. You can add a sub-requirement for the failure handling to complement the higher-level requirement.

Use Case Diagram (1/5)

• Most importantly, use cases should not be written with ambiguous terms that may be interpreted variously.

• Actors should be defined concretely.• For example, “User” is not enough to describe various types of users of your

system. There can be “Customer”, “Staff”, “Administrator” and so on, if needed.

• In the system boundary, only functions that you will develop can be included (i.e., specified).

• It is wrong if you specify 3rd party system’s functionalities in your system boundary, because you will not develop them.

• Please check whether each function is developed and functioned in your own hotel reservation system.

• It seems that some teams did not validate the completeness of their use case diagram adequately.

• Some basic/essential functions were not specified.

Use Case Diagram (2/5)

• Some additional functions/features that our customer requested (Addendum) are not included in your use case diagram.

• <Create an account>, <Log-in (Sign-in)>, <Log-out (Sign-out)>, <Pay fee for the reservation>, <Get room information>, <Send an email/SNS message>, <Manage membership> and so on.

• Of course, some of them can be included as steps in other use cases, or they can be described with different names.

• Use case relationships should be used for their own purposes.• An “included use case” should be reused by multiple use cases. If not, it is

not necessary to add a use case for the inclusion.• An “extending use case (A)” should be executed optionally by an extended

use case (B). The extending use case (A) extends the range of functional steps of the extended use case (B) optionally. So, the <<extend>> relationship is usually used for handling some additional situations such as error handling.

• “Generalization & Specialization” are very similar to the “inheritance relationships” in OO programming. A subclass inherits all of the features of its superclass, and the subclass is specialized based on the inherited features to perform a specific function. The same idea works on a use-case diagram.

• Except above three relationships, only communication lines are allowed between use cases in U.C.D.s (solid line without any arrow)

<<include>>

<<extend>>

Use Case Diagram (3/5)

• For more effective description of use cases, modularization of your HRS is recommended.

• Please modularize your own HRS as much as possible when you will refine your use-case diagram(s).

• The modularization should be consistent with the hierarchy of requirements.

System boundary

Actor

Use case

Use case

Use case

Use case

Use case

Use case

<<include>>

Current version of use case diagram

Use Case Diagram (4/5)

• For more effective description of use cases, modularization of your HRS is recommended.

Modularized use case diagram (High-level use case diagram)

Use Case Diagram (5/5)

• For more effective description of use cases, modularization of your HRS is recommended.

• High-level first, low-level later

Refinement of use cases: High-level & Low-level use case diagrams

<<Agent>>PurchaseMonitor

<<Agent>>PurchaseManager

Keep NSM Needs Updated

Predict Student Needs

<<include>>

High-level use case diagramLow-level (Module-level) use case diagram

for each module/package/subsystem

Use Case Description (1/2)

• Recap: “How to write a use case description”• What marked in red are the frequently wrong details.

Use case description detail What the detail means and why it is useful

Related Requirements Some indication as to which requirements this use case partially or completely fulfills.

Goal In Context The use case’s place within the system and why this use case is important.

Preconditions What needs to happen before the use case can be executed.

Successful End Condition What the system’s condition should be if the use case executes successfully.

Failed End Condition What the system’s condition should be if the use case fails to execute successfully.

Primary Actors The main actors that participate in the use case. Often includes the actors that trigger or directly receive information from a use case’s execution.

Secondary Actors Actors that participate but are not the main players in a use case’s execution.

Trigger The event triggered by an actor that causes the use case to execute.

Main Flow The place to describe each of the important steps in a use case’s normal execution.

Extensions A description of any alternative steps from the ones described in the Main Flow.

Use Case Description (2/2)

• In many teams, <Main Flow> was too abstract to draw an accurate and correct sequence diagram.

• Each step should include participating actor(s) as accurate as possible.(Except for the steps that can be interpreted clearly without any actor)

• If a step uses data, sending/receiving/processing of the data should be specified as precisely as possible.

• Who makes the data, Who sends the data to whom, Who receives the data from whom, Who processes the data and how

• If your team uses <<include>> or <<exclude>> relationships, corresponding descriptions should explain them.

• For <<include>> relationships (A includes B), the description of the including case (A) should contain <Included Cases>, and put “Include::B” as one of the steps into <Main Flow>. (See UML Supplementary Materials)

• For <<exclude>> relationships, <Extensions> can be used to describe branching (optional) actions.

• For the generalization/specialization relationships, a sub-use case should include <Base Use Cases> information in the description table

Domain Model

• 5~15 concepts (objects) are appropriate to represent the domain.

• The domain model is used to ensure clear understanding of the domain of your Hotel Reservation System. No more information is needed.

• The domain model is used to describe a world to which your system will provide service, by specifying concepts and relationships.

• The domain model is a static model, so time flow with sequence of events or information flow are not shown in the domain model.

• The domain model does not include software. In other words, the domain model should not include “development-specific” information that can vary depends on the development methods.

• Therefore, describing <Hotel Reservation System> in your domain model is wrong

• If we want to describe a world for <Course Registration System>, the domain model may include “Course”, “Student”, “Professor”, “Credit”, “Registration Form”, “Registration Period”, and so on.

• Also, your domain model should not miss any important concept to adequately describe the domain.

Sequence Diagram (1/2)

• Use case diagram, use case description, and sequence diagram form a trinity.

• An use case description reveals the detail of an use case, including pre-conditions, post-conditions, triggers, interacting actors, main flow and alternative/exceptional flows. A sequence diagram shows the information and flows in a graphical way.

• Their contents should be consistent. There can be minor differences in views, they are describing the same thing. Thus,

1. Their names should be matched to the corresponding things.

2. Participants should be consistent with the ones which you defined in the use case description.

3. The main flow of the use case description should be expressed in the sequence diagram.

4. Any other flows (e.g., alternative, extensional, or exceptional) should be expressed if they are defined in the UC description.

5. Irrelevant contents, or in other words, unmentioned contents in the use case description, should not be in the sequence diagram as well.

Sequence Diagram (2/2)

• Messages should be able to express the flow in detail.• One (or more) step in the flow of the use case description, can be expressed

as several messages in the sequence diagram.• Messages are similar to function(method) calls.

• Sometimes, it would not be possible that one step in the use case description is translated into one or more messages in the sequence diagram. However, the overall order of messages still should be kept.

• Please for each message, use the name which can reveal the goal or content of the message.

• Any information which is delivered from one to another participant, should be defined as parameters.

Preliminary User Manual

• Be consistent to what you have analyzed and designed.• Show how to use the functionality that you have analyzed and designed.

However, do not show things about what you didn’t design before.• User may be confused if those functionalities are not found, not executable,

or not matched to the actual function in your system.

• [Suggestion] It would be better to define happy case of your system for user’s understanding.

• “Happy case” is that most likely expected scenario when an user properly use the system.

• Users want to find, in the user manual, how to do what they want to do. Think about the happy case, and describe the manual following the case.

Acceptance Criteria

• Acceptance Criteria are the conditions that a software product must satisfy to be accepted by a user, customer, or in the case of system level functionality.

• Acceptance Criteria are a set of statements, each with a clear pass/fail result, that specify both functional and non-functional requirements. Acceptance criteria constitute our “Definition of Done.”

• Acceptance criteria define when a work item is complete and working as expected. Express criteria clearly, in simple language the customer would use, without ambiguity regarding the expected outcome.

• The Given/When/Then format is helpful way to specify criteria:“Given some precondition When I do some action Then I expect some result.”

• To derive criteria effectively, you can set some ‘user stories,’ how users are expected to use the system.

• Most teams specified criteria for functional requirements.

Ref:https://www.leadingagile.com/2014/09/acceptance-criteria/http://www.boost.co.nz/blog/2010/09/acceptance-criteria

Non-functional Requirements

• Various factors affect the system’s functionalities.• Non-functional requirements describes the requirements on various factors

which affect the functionalities.• You need to write non-functional requirements in words as clear and

concrete as possible. (Just like functional requirements!)• There are many types of non-functional requirements. You can refer to the

Appendix that we provided in the description for Project 2.

Guideline for Project#3How to refine your analysis/design?

Sprint Backlog

• Goal• To describe a vision statement for this sprint

• The overall goal of the system development

• A strategy or strategies to lead your team to success

• User stories• To elaborate one or more user stories that cover the goal of this sprint

• User story(stories) will be written as a happy (best) case scenario that can help stakeholders understand your system’s goals and functionalities easily and clearly.

• User story(stories) will describe your system’s requirements in the form of storytelling

• User story(stories) will describe how your system will satisfy users’ needs

• Requirements• To make a table to list functional/non-functional requirements

• The table should include Requirement IDs.

• The table may have a hierarchical structure to describe the functionalities of your system after the refinement of previous version of requirements.

• Tasks• To list up the tasks hierarchically, which should be done in this sprint to

develop an initial version of HRS.• Each task should contain a Task ID, a short description, and related requirement IDs.

System Design (1/5)

• System Architecture• System architecture should be able to provide a blue print of your system by

describing the structure and some relationships between the components.• “Imagine an architectural drawings for the building construction”

• A format for describing a system architecture is not fixed.

System Design (2/5)

• (Refined) Use Case Diagrams & Descriptions• To draw a refined use case diagram that reflects the feedback.

(Your system should be effectively modularized at this step)• Highlight the refined(modified)/modularized parts of the diagram in red

• To refine your use cases and describe them with tables (as Project#2)• Highlight the refined parts of the description tables in red

Use case name Create a new Blog Account

Related Requirements Requirement A.1.

Goal In Context A new or existing author requests a new blog account from the Administrator.

PreconditionsThe system is limited to recognized authors and so the author needs to have appropriate proof of identity.

Successful End Condition A new blog account is created for the author.

Failed End Condition The application for a new blog account is rejected.

Primary Actors Administrator.

Secondary Actors None

Trigger The Administrator asks the CMS to create a new blog account.

Included Cases Check Identity

Main Flow

Step

1

2

3

Action

The details are provided to the system.

The Author Credentials Database verifies the details.

The details are returned as verified by the Author Credentials Database.

Extensions

Step

2.1

2.2

Branching Action

The Author Credentials Database does not verify the details.

The details are returned as unverified.

System Design (3/5)

• (Refined) Sequence Diagram• To draw refined sequence diagrams.

• At this sprint, it is important to consider your team’s design/development patterns & methods & styles that you will actually use.

• If there were ambiguous participants or interactions (i.e., messages/ordering), your team should describe them as clearly (i.e., unambiguously) as possible by the refinement.

System Design (4/5)

• Class Diagram• To identify classes for the implementation

• What class will you implement in your system? (e.g., in Java/Python/HTML)

• To design classes for the implementation by specifying identified classes and relationships between the classes.

• Relationships should be properly used to design classes of your system

System Design (5/5)

• Class Diagram• To identify classes for the implementation• To design classes for the implementation by specifying identified classes

and relationships between the classes.• Relationships should be properly used to design classes of your system

Sprint Review

• Achievement• 1) Task achievement table in the form of check-list to show how much your

team achieved the original plan you made at the beginning of the sprint• 2) Table of requirement validation results

• For functional reqs: test input, expected output, actual output, test result• For non-functional reqs: goal, actual output, satisfaction result, reason why it is

satisfied or not

• Demonstration• 1) Screenshots of your implementation results following the order of your

team’s user story• 2) Remarks of requirements IDs on related screenshots.

• Development Environment• Description of your environment for 1) development and 2) testing

• Programming Language• Used platform/framework for development/testing• Desktop & server information for development/testing