The specifications (or specs) are components of a document from which a developer can develop the system. It should be complete enough that it could be used as a bid request out to a third party.

In general, the system specifications will be developed from discussions with your client.

The specifications include:

  1. user stories
  2. requirements (functional, non-functional, interfaces, other)

1. User Stories

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

User stories are developed during and after discussions with the client. Clients are asked to talk about the system they imagine... who will it serve, what problems will those users be able to solve with it, what activities are envisioned, which type of user will be doing what? Are there existing systems or programs that must be interacted with or incorporated into the new system? What are the data requirements? What needs to be stored? Collected? Generated?

Video: User Stories

2. Requirements

The requirements should be no more than 2 or 3 pages. It will be primarily gathered from the user stories and the use cases but will also include any specific needs of the client that are identified but not specifically written into user stories or use cases. Remembering that the requirements define the "acceptibility" 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 is the collecting and collapsing of information from the user stories into commonly-expresed requirement statements. 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 little to assist you in organizing and directing your semester's work. Prioritization need not be a pure numerical order, but should identify 3 groupings of priority:
  1. definite: requirements we will definitely have functioning by semester end

  2. perhaps: requirements we may well have time to get to, but not until category "definite" is done

  3. improbable: requirements identified by the client that we most likely won't have time to meet this semester but not until category one is done

Requirements Categories

Organize your requirements section with the following subsections. In each subsection, have the 3 priority levels (above) clearly identified. Some subsections may be empty, and/or some priority levels within subsections, depending on the nature of your particular project.

See the video below for a better explained list of areas from which you can draw non-functional requirements.

Video: Requirements

Some Specs Employ These

But your project will not need to do so. This information is here for personal edification and for historical reasons.

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.

Video: Basic Use Cases

Video: Identifying the Actors

Video: Developing the Scenarios

Video: Diagramming Use Cases