Functional Specification

1. User Stories

User stories are short statements of one specific experience a user will have with the system to be built. They are experssed in 1, 2, maybe 3 sentences and often put on index cards to enforce their brevity. User stories are a good starting point in getting the ideas a client has about the needed system into a concrete form.

2. Use Cases

Based on user stories and personas (which we are not using for this project), use cases capture the needed system functionality from a developer's point of view.

There are two forms of use cases that are often used: a graphical form (diagram ) that shows how the different use cases relate to each other and a textual form that talks about the details of each use case. For your projects, we will do the textual form first and then develop diagrams.

Associated with each case needs to be a description of the user, referred to as the user type, or actor. This needs to be in enough detail to allow you to reason about the task. User types may or may not map to unique use cases. For example, the one time user and the repeat user are most likely different user types. Depending on the interfaces, they may use the same interface. In this case, there will typically be an optional step of checking the help information. If they use different interfaces, they will have different use cases. Use cases should address all types of end users as well as administrators. Pay special attention to first time uses as they often have a different set of tasks that are being performed.

A single use case goes on to describe a scenario in which the actor interacts with the system to achieve some goal. The scenario will often have steps showing the order and nature of smaller actions that comprise the full behavior.

The detailed use case needs to include error cases. Identifying the error and unusual cases is one of the most valuable parts of use cases, as designers and developers often miss a number of these points.

3. Requirements

The requirements document should be no more than 2 pages. It will be primarily gathered from the user stories and the use cases but will also include any specific needs of the client. Remembering that the requirements define the correctness of a program, you can expect me to go through the requirements at the end of the course and see if you have met them.

One of the key values of the requirements document is the collecting and collapsing of information from the user stories into common requirements. Some of them may get translated into programming terms rather than domain and user terms. For example, if there are two different file structures that are needed, one of the requirements might be the consistency of the two structures. Or as you work through the different use cases of a game, you will find related behaviors; identifying how those behaviors need to be consistent might be another requirement.

A key part of requirements is that they must be prioritized. A list of requirements without prioritzation does nothing to help understand what needs to be done. Prioritization need not be a pure numerical order, but must at least identify 3 or 4 levels of priority.

Requirements will also capture any platform or performance constraints. For example, the ability to port to another platform is a requirement. The necessity of using a particular tool or platform is a requirement. The need to run on old machines is also a requirement. See the video below for a list of areas from which you can draw non-functional requirements.

If your application is not permitted to do something -- such as overwrite a file or share certain components -- you should identfy these as constraints or inverse requirements.