Documenting Requirements

User stories are used in many devleopment processes.
User stories describe what a user wants to do from their perspective

User stories come from client discussions, and they are often informal at first prior to analysis.

Informal

  • Can be written by any stakeholder
  • Sometimes even hand-written
  • Non-functional requirements often included

Structured

  • Formalised version of the informal requirements, ie:
    AS A client I WANT the ability to START AND STOP SERVERS.

Priority

  • Each requirement should be given a priority
  • This is important for planning and discussion

Acceptance Tests

  • As requirements are gethered, acceptance tests can be included in user stories
  • These offer a method of confirming that a requirement is properly implemented
  • It can often enhance the understanding of a requirements
  • Acceptance tests describe what should happen if the requirements are properly implemented

Actors

  • An actor refers to a user of the system
  • Use cases may include more than one actor
  • An actor may perform more than one action or be in more than one use-case
  • Actors are not a part of the system, though they may
    • Use it
    • Provide functionality to it
    • Recieve information from it
    • Provide information to it

Actors can be identified by looking for the roles in the system.

System Boundary

The system boundary defines the cope of a system, actors are outsie of it, whilst use cases are inside it.
It is often drawn as a rectangle around use-cases.
Actors are outside of the system boundary.

Actors can be associated with a use case, associations are shown by solid lines with arrowheads showing who initiated the interaction.

Use Cases

Use cases describe the functional requirements.
Use cases often describe what occurs between a system and a user as a sequence of actions.
They are often written in the form of user stories or scenarios.
Use-cases are drawn as an ellipse

Use cases should contain both succes and failure cases. They should include diagrams and descriptions.

Use cases:

  • Are interactions or dialogues between a system and actors
  • Show messages echanged and actions performed
  • Normally include alternatives and exceptions
  • Are initiated by actors and may involve many other actors

Use-cases can be identified as they are the “actions”/“functions” that are in a problem statement - what an actor/user will do with the system.
Further analysis can be used to give use-cases sub-processes.

Use-case relations

Includes

A base use-case contains an inclusion use case
A base use-case executes up to the inclusion point - the inclusion use-case executes, and the base-case completes

Extends

An extension use-case augments a base use-case if an extension condition is satistifed
Base case executes up to the extension point, and the extension may execute if the condition is met

Generalisation

A generalisation relation between use-cases indicates that the specialised use-case is consistent iwth the generalised use-case, not unlike inheritance in OOP.
A specialisation use-case cna substitute a generalised use-case, using any parts of the interaction of the generalised case.

It is also possible to use generalisation for actors (a specialised actor being more consistent with a generalised actor - possibly adding more information)
A speicalised actor inherits characteristics of a generalised actor when it substitutes it.

Use-case descriptions

Use cases are typically described with the primary success scenario as a series of steps.
Non-success scenarios are exceptions.

Use cases should have an:

  • Id
  • Title
  • List of actors
  • List of preconditions
  • List of postconditions
  • Detailed event flow for success and exceptions

Ideally, use-cases should be named using “verb-noun phrases” and actors should be described and thier stake in the use-case should be described, ie:

  • A programmer is responsible for implementing the project

Use case diagrams must have an associated use case description

Example use case

Id - Title: MC0001 - Create Minecraft Server
Purpose: Creates a Minecraft server on behalf of the user with the specified details
Actors: User, Server Database, Node Database, Selected Node
Pre-conditions: User must be logged in
Post-conditions: The node must have been allocated succesfully and the server details stored on the database

Event flow:

  1. User selects “Create Server” from the dashboard
  2. User inputs the server name, RAM, storage and selects te server software
  3. User selects “Create”
  4. A node is allocated and server details are stored in the database

2a. The user inputs an existing server name 2a1. Warn the user that the name is already taken 2a2. Return to the dialog to allow the user to change it

3a. The user selects “Create” without inputting all fields 3a1. Warn the user 3a2. User adds the missing information

4a. The node is already allocated or no free nodes exist with the desired specs 4a1. Display an error to the user 4a2. Return to the dialog to allow the user to change their configuration