Introduction to Team Collaboration

Guest talk by Michal Antkiewicz (Research Engineer @ Waterloo Intelligent Systems Engineering Lab)

Project Management

What are we trying to do?
Who is doing what
When is what we are doing supposed to be finished
Why is what we are doing relevant to users

Many approaches but for small team projects agile processes are best

https://www.agilealliance.org/agile-essentials

Work on user stories and break them into small tasks
Design, implement, test, and deliver complete functionality to users during a sprint

Example Project Management (I)

Within a project, group tasks by user stories and, inside, by task status:

Open (not assigned and not started)

In Development (assigned to a person and started)

Ready for evaluation (code ready for testing)

Completed (code merged and deployed)

Backlog (not part of any user story, but maybe has to be done eventually)

Abandoned

Example User Story

“As a <role>, I want <goal/desire> so that <benefit>”

“As a …behavior planner developer,
I want to …execute test scenarios in simulation,
So that …I can ensure that the behavior planner makes correct decisions in the given scenarios.”

Talking to our users we can get the user stories (Requirement Analysis)

Task Status Lifecycle

Open [ ] Add pass parked scenario <= Unassigned, not started
In Development [ ] Add drive straight scenario (assigned to Bob, due on Jan 20, 2019) <= Assigned, due date specified
Ready for evaluation [ ] Add T-intersection scenario (assigned to Carol, due on Jan 15, 2019, merge request) <= PR/MR ready, reviewers assigned
Completed [X] Support launching the simulator to execute the given scenario (Alice, Jan 09, 2019, merge request) <= PR/MR merged

Example Project Management (II)

Weekly status and planning meetings:

Walk through each user story

Discuss last week progress, difficulties, plans for the next week

Check off completed tasks

Capture conclusions as new user stories, tasks, or comments in existing tasks

A weekly meeting can be in person or online but they are critical to keep the team cohesive.

On-demand meetings to discuss some topics in-depth (plan, design, present results, discuss technical issues).

Source Code Management

Organization

Do on github/gitlab

Version control is necessary to keep track of code history and manage evolution.
- A snapshot is a version of code at the given time; snapshots from a tree
- A branch is a sequence on snapshots with a head pointing at the last one
- Applying (committing) changes to one snapshot creates a new one
  - Write good commit title
Multiple source code repositories can be used to allow for independent development of parts of the system by many teams. Source code for the whole system created by composing the repositories.
- Repositories can be composed using submodules, which include the contents of the submodule into a folder of the parent repository
- A submodule is a pointer to a snapshot in a different repository
Branching within a repository necessary to separate and manage concurrent work streams by team members.
Code merges between branches deliver increments of functionality and allow for code review and testing.

Building

Reproducible builds are necessary to ensure the system works the same on developers’ machines as well as on the target machines.

Version management ensures the correct versions of components are used; however, it is also necessary to control versions of code dependencies (operating system, libraries, drivers).
Reproducible builds help avoid the “works on my machine” problem and enable continuous integration (CI) and continuous deployment (CD).
Two prominent technologies are commonly used today: containers (e.g., Docker) and immutable package systems (e.g., Nix).

Example

Create automated dependencies install script
- automatically configure development environment so that it is consistent among all developers.
Using Travis CI and Circle CI services to execute automatic builds for every pull request.
- CI services can execute the build within a docker container, which reproduces full installation and build on a fresh machine. The containers can also be cached, to prevent starting from scratch.
- It is also possible to run local builds within a docker container on a developer’s machine, which solves the conflicting dependencies problem (when different projects depend on different versions of the same dependency).

Testing

Automated tests are necessary to ensure that existing functionality works as expected after the code is modified.
Unit tests ensure functionality within a component works as expected.
Integration tests ensure that components work together as expected. System tests ensure that the entire system works as expected.

Requirements Engineering

Requirements Engineering is a systematic approach to eliciting, organizing, and documenting the requirement of the system, and a process that establishes and maintains agreement between the customer and the project team on the changing requirements of the system.

Requirements engineering deals with elicitation, analysis, specification, and validation of requirements

The Three Phase of Requirements Engineering

Idea of a new product

to solve some problem in the real world

Requirements development

the process of creating the requirements spec

Requirements specification

the document that describes what has to be built, not how

Major factors of software project failure

Lack of user input
Incomplete Requirements & Specs
Changing Requirements & Specs
Unrealistic expectations
Unclear Objectives
Unrealistic Time Frames
Communication problems

Requirements specification

Requirement specifications include product mission, stakeholders, scope, constraints and assumptions, and requirements

Purposes of a requirements spec documents

A requirement spec document is used by many different stakeholder for different purposes:

Customer - part of a formal contract
Manager - basis for the project plan
Developer - basis for the design and implementation
Tester - document to test the system against
Maintainer - starting point for understanding the system

Content of a requirements specification

Purpose of the product
Stakeholders
Scope of the product
Requirements constraints
Assumptions
Requirements

Purpose of a product

Concise statement of the business problem to be solved

The mission statement should be

concise (about half a page)
pure text (no figures, tables, formulas, etc.;) – primarily present tense
limited jargon and acronyms
good grammar and spelling

Expected elements

Opportunity and problem
- What is the opportunity that your software will exploit?
- Who will use it?
- What problem will it solve?
Objective
- What does this system/project will accomplish within the given context?
Plausible design approach
- What is the high-level solution approach that will be pursued?
Expected benefits over existing alternatives if any

Example of Product Abstract

Sample Abstract (to be improved):

Sana is a cross-disciplinary organization that uses open-source technologies to improve healthcare around the world. Sana Mobile, an initiative of the organization, allows doctors to formally define medical procedures using an XML syntax known as the Sana Protocol. Sana Protocol Builder is a graphical web application which aids doctors in the creation of these procedures, automatically generating the resulting XML for use by remote field workers via the Sana Mobile app.

Sample Abstract (now including the expected elements):

=> Opportunity

Sana is a cross-disciplinary organization that uses open-source technologies to improve healthcare around the world. Sana Mobile, an initiative of the organization, allows doctors to formally define medical procedures using an XML syntax known as the Sana Protocol in order to improve their repeatability and quality control and ultimately their success rate.

=> Problem

A major obstacle in reaching these benefits is the lack of a usable tool that would allow doctors to easily create such protocols.

=> Objective
Our objective is the develop Sana Protocol Builder to address this challenge.

=> Plausible design approach
We envision the solution as a graphical web application for defining the procedures from predefined templates, which will then automatically generate the resulting XML for use by remote field workers via the Sana Mobile app.

=> Expected benefits over existing alternatives
The resulting application will provide an easier to use, less error prone, and faster solution than the current approach of using a generic XML editor to define the protocols.

Stakeholders

People and organizations interested in the product.

Accurately determine and describe the stakeholders, they are the main sources of requirements

Customers, users, regulators, developers, architects, domain experts, analysts, marketing people, sales people, management, etc

Scope of the product

Determines the boundaries of the work to be studied
Can use a context diagram to define the scope

Requirements constraints

Global requirements having an effect on all or most of the requirements
Solution Constraints
- Describe any mandated design or solution constraint
- E.g.: The system must run on Linux.
- Identify partner applications
  - E.g.: The product will interface with an existing module written in C.
Project Constraints
- Time constraint: Must release the product at the 2020 Olympics.
- Financial constraint: Indicates how elaborate the product can be.

Assumptions

Assumptions listed here are those being made by the project team

If the assumptions are not satisfied, the success of the project may be endangered.
- E.g., assumptions about performance or capacity of the hardware used, interfaces between the new and existing products

Requirements

Requirements are

the things that the product must do to achieve its purpose
- functional requirements => What the system does
the qualities the product must have
- quality (aka non-functional) requirements => How well the system does it

Requirements should be unambiguous, consistent, complete, verifiable, and free of implementation bias

Functional Requirements

Functional requirements state what functions the system should perform

Functional requirements vs. Technical requirements

Think of the functional requirements as the business requirements

You may introduce technical requirements during designing a solution for the functional requirements because of the technology used by your solution

Example:

The system will allow the user to view the layout of seats in an aircraft.
A given seat can be assigned to at most one person at any given time.

Quality Requirements (Non-Functional Requirements)

quality requirements state with what quality it should perform

Look and feel
- specify the intention of the appearance
- E.g. The product shall provide a graphic view of all the roads. The graphical interface should conform to the XXX GUI Style Guide.
Usability
- Consider your intended audience and their skill levels
- has to be easy to use
- E.g. The product shall be easy to use by people who may have only one hand free.
Performance
- These requirements are written when there is a need. If a task is to produce a monthly summary report, there may not be a need to produce it quickly.
- May consider the following attributes:
  - speed to complete a task
  - accuracy of the result produced
  - safety to the operator
  - volumes
  - ranges of allowable values,
  - throughput (e.g. rate of transaction)
  - efficiency of resource usage
  - reliability (expressed in terms of mean time between failures)
  - availability (up time)
- E.g.: The product shall identify an aircraft within 0.25 seconds.
Operational
- These describe the environment in which the product is to be used
- e.g., The product shall be used by mobile technicians who may remain disconnected from the server for an extended period of time.
- Consider if the product must collaborate with other products, or access outside databases. This is revealed in the product use case diagram.
- Operational environments can cover:
  - operating environment,
  - condition of users – are they in the dark, in a hurry, …
  - collaborating systems,
  - portable products.

Maintainability
- The exact amount of maintenance needed later may not be known at the time of writing the requirements. However, if this can be foreseen, it should be specified, e.g.,
  - The product shall be readily portable to the Linux operating system.
  - The product shall be translated into various foreign languages.

Reliability
Security
- Confidentiality – data stored (or transmitted) by the product is protected from unauthorized access and disclosure.
- Integrity – the product’s data are the same as the source of the data.
- Availability – the product’s data and functionality are accessible to authorized users.
Safety
Cultural and political
- The best way to find cultural requirements is to take help from someone from that culture.
- Following are some items you may consider cultural or political:
  - Acceptable solutions – e.g., should all components be made in XXX?
  - Unacceptable solution – the product must include no product made in YYY.
  - Political correctness
  - Spelling
Legal Requirements
- Start with your company’s lawyers to know which law is applicable.
- Consider adjacent systems and their legal requirements. (privacy to data, proof of transaction, nondisclosure??)
- Are there any laws that are relevant to this product? (data protection, privacy laws, consumer protection, right to information, …), e.g., The product shall comply with the FCC regulation so and so.

Acceptance Criteria

All requirements must have acceptance criteria (or fit criteria), being a benchmark such that the test engineers can compare the delivered product with the original requirement.

Necessary properties of requirements

Unambiguous

the meaning should be clear

Consistent

one requirement must not contradict another

Complete

E.g.: “The process is terminated if the wrong PIN has been entered more than a certain number of times.” (What is that number?)

Verifiable (possible to test)

a requirement that cannot be tested is not a requirement

E.g.: “The system should work in real-time mode.” (What is “real time” here?)

Desirable properties of requirements

Free of implementation bias

What vs. how

Specification vs. solution

E.g.,

“The system shall accept a password when data is accessed.” X

This has a requirement to use password

“The system shall ensure that the data can be accessed only by authorized users.” V

This gives you an opportunity to search for alternatives

Feasible

It should be realizable with reasonable effort

Acceptance Criteria for Functional Requirements

Each user story gives rise to an acceptance test.
The functional acceptance criteria is that the given actions complete with the correct results.
- Specifiable in a precise terms to be checked automatically, or it may need to be checked by a domain expert

Acceptance Criteria for Quality Requirements

vague, ambiguous, and not at all lending itself to numbers
- find a way to measure it
- e.g.
  - having a set of standard tasks and measuring the learning time needed before being able to do them successfully.
  - specifying an amount of training time needed before being able to use the product to a certain standard.
  - counting the number of calls to a help desk or references to on-line help.

Requirements Engineering Process

Starting your Project

Determine the purpose of the product
Create a list of stakeholders
- Consider typical parties with interest for the project
  - e.g., users, customers, managers, domain experts, architects, analysts, marketing people, salespeople, and developers
- Know your customers, what they want, understand their problem, etc.
- Determine others who have an interest in the product
  - Government, special interest groups, etc.

Determine requirements constraints
- Schedule and budget constraints, technology constraints, etc
Scope of your work
- Decide how much work you will study before determining the requirements for the product. Keep in mind the product’s purpose.
Domains of interest
- Domains are subjects that you will need to know something about if you are to build a product.
- For example, when building a self-driving car, you need to understand the driving task, traffic safety, robotics, machine learning, embedded hardware and software, automotive systems, etc. Where will you go to get information about each domain?
Risk analysis: Assess the risks that are most likely to happen, and the risks that would have the greatest impact if they become problems
- For each risk, assess the probability of it becoming a problem, and its impact on cost and/or schedule
- The risks that are most relevant at the requirements analysis are:
  - Absence of a clear and measurable purpose for the product
  - Lack of stakeholder involvement
  - No measurements put on requirements
  - New or unknown business area with uncertain needs

Requirements Development

Commission/fixed price

Requirements documented up front as completely as possible
Basis for effort estimation and contract price

Participatory design - evolutionary development

Basically Agile Development
Minimizing risk

Challenges of Requirements Elicitation

There is no such thing as the “complete and well defined requirements that just wait to be discovered”

Requirements depend on available resources and skills

Different stakeholder (e.g., users, customers, managers, domain experts, and developers) have different perspectives, skills, and desires

All stakeholders gradually change their minds, learn, and make compromises during the process

Requirements are developed in a process of cooperative learning, by being recorded, prioritized, negotiated, evaluated, and documented

To come up with requirements, you need:

Distributed knowledge
- Several people, departments, organizations
- Different viewpoints and goals
Tacit knowledge
- Things that are obvious to experts
- People find it hard to describe knowledge they regularly use
Domain experts usually don’t have time
- They are the most valuable assets to a company and use their time to earn money for the company in its core business
Political problems
- Not everyone may have a positive attitude towards the introduction of a new system
- New software systems often mean changing who has power and who not

Requirements can also come from:

Interviews

Have to be carefully prepared and possibly recorded

Questionnaires

Have to be carefully prepared and tested

Groupmeetings

e.g., brainstorming, focus groups

Existing documents

Existing systems

Prototypes

Requirements need to be negotiated to find an agreement that makes everyone (of the stakeholders) happy

We want Win-Win outcomes – everyone is a winner

Proposed Solution	Winner	Loser
Quick & Dirty	Developer & Customer	User
Lots of “bells and whistles”	Developer & User	Customer
Driving too hard a bargin	Customer & User	Developer

Prioritize Proposed Product Features

Ease of realization (input from engineers) vs Business importance (input from the customer)
Have to Prioritize the hardest and most important

Critical Factors in Requirements Development

Who is responsible for creating the requirements specification document?
- Customer or the commissioned software development company?
- Complete requirements specification document up front vs. evolutionary development
Efficiency of the communication depends on
- Number of stakeholders
- Group communication vs. individual communication
- Communication medium
  - Meeting
  - Tele-/video conferencing
  - Groupware system
  - Telefon / e-mail

Requirements Specification Documents

A requirement specification document is used by different people:

Customer - project contract
Managers - project planning
Developer - basis for design and implementation
Tester - basis for testing
Maintainers - basis for understanding the system

In Traditional Requirements

Each requirement has to be given an ID

May be defined by a one or few sentences

May use diagrams if useful

In Agile Development we use User Stories.

A user story is one or more sentences in the everyday or business language of the end user or user of a system that captures what a user does or needs to do as part of his or her job function. (*)
User stories capture primarily functional requirements
But can also be used to capture non-functional requirements
“As a <role>, I want <goal/desire> so that <benefit>”

As a user closing the application, I want to be prompted to save anything that has changed since the last save.

As a system administrator, I want to add a new user to the system.

Exercise Questions

Revisit functional requirement (F) vs non-functional (quality) requirement (N)

Functional Requirement: what functions the system should perform
- No technical mentioned
- “how the system should perform”
Non-functional Requirement: quality requirements state with what quality it should perform
- More like technical requirement, e.g. performance, implementation, safety concerns
- Has nothing to do with “how the system should perform”

For each requirement below, indicate whether it is a functional requirement (F) or a non-functional requirement (N):

The system should be designed so it can be later extended to handle a frequent- flyer plan.

N.
This is clearly a implementation concern.

The system will allow the user to view the layout of seats in an aircraft.

F.
Only involves how the system should perform.

The system must be available at all times. Only 2 minutes of downtime per week is to be permitted.

N.
This is a performance concern.

A given seat can be assigned to at most one person at any given time.

F.
Only involves how the system should perform.

The online shopping system shall allow the shopper who initiated an order or a senior manager to cancel the order anytime before shipment.

F.
Only involves how the system should perform.

The system shall prevent any unauthorized person, that is, one other than the shopper who initiated an order or a senior manager, from canceling the order.

N.
This is a safety implementation concern.

After requesting the cancellation of an order by a user, the system shall provide the user with an acknowledgment whether the cancellation was successful or not.

F.
Only involves how the system should perform.

The acknowledgment shall be displayed to the user no later then 15 seconds after the user has requested the cancellation.

N.
This is clearly a implementation concern.

Revisit “Necessary properties of requirements” and “Desirable properties of requirements”

Necessary properties of requirements

Unambiguous (the meaning should be clear)
Consistent (one requirement must not contradict another)
Complete E.g.: “The process is terminated if the wrong PIN has been entered more than a certain number of times.” (What is that number?)
Verifiable (possible to test: a requirement that cannot be tested is not a requirement)

Desirable properties of requirements

Free of implementation bias (Only What, Not How; Only Specification, Not Solution)
- It should be realizable with reasonable effort

For each of the following statements below, indicate whether it would be appropriate as a requirement or not. If not, provide an explanation and suggest an improvement.

The automatic teller machine will have fast response time.

Inappropriate. This performance requirement is not testable. It could be corrected by specifying minimum response time for specific requests or for all user requests.

The name list will be sorted in alphabetical order using quicksort before printing.

Inappropriate. It has to be Free of implementation bias. Quicksort algorithm term should be removed.

The system will be easy to use.

Inappropriate. This requirement is not Verifiable nor testable. It could be corrected by specifying efficiency and effectiveness targets for performing specific tasks by users with specific training.

The system should allow a user to display previous orders placed from the user’s account, which are stored on the hard disk.

Inappropriate. It has to be Free of implementation bias. The solution “stored on the hard disk” us should be removed.

The system must be highly available. Only 2 minutes of downtime per week is to be permitted.

Appropriate. The requirement is clear, consistent (highly available | 2 minutes downtime per week), Complete (2 minutes instead of few minutes), Verifiable (possible to test).