Requirements Analysis, the first stage in the software lifecycle, is the process of defining the capabilities of a system that must be met upon project completion. The length and content of a requirements document depends entirely on the scope and depth of the required system, so anything from a few pages to a few books.

The content of a requirements document also varies depending on the scope of the project, for example a critical stage such as stakeholder identification could be omitted completely if our system is being built for internal use in a single-person organisation.

In this article, different sections of a requirements document will be examined, and an example provided which will relate to TCdev Snacks (an ongoing project).

Document Structure

Our first port of call is the structure of the document. For a number of years now I have always used the same few base items:

• Application / Project (what is this document being written for?)
• Description / Content (what is in this document?)
• Item Reference (particularly useful when referring to a range of documents)
• Version History (are we looking at the most up-to-date document?)

As this is a client-facing document, we may wish to add sections such as a distribution list (who is this document to be sent to) or an internal review list (to show who has had input in the document content).

Finally, this is the requirements document, so we will need a signature from the client to ensure that all of their system requirements have been recorded and defined. An authorisation section will be required at some point.

One important note is that a document is far easier to read, discuss, and refer to if there is a good use of item references. To this end, sections should be numbered. Discussing a document with a client and referring to ‘section 4.2’ rather than ‘about half way down page 11’ saves time, effort, and is infinitely more professional.

Overview

Now that we have our document structure sorted, we should provide a brief overview of the current processes, the proposed system, and our objectives.

The system objective should clearly describe what the purpose of the proposed system is without being too specific. Although the end result of most systems is ultimately to increase profit, this is never the main system objective. To quote my example document:

…the overall objective of this system is to reduce the time spent on data upkeep, giving actors more time to spend on acquiring new customers, managing deliveries, and finally increasing profit.

Next we should describe the benefits of the proposed system, which may be completely unrelated to the objectives (maybe even unexpected) but still worth highlighting. In the example document, one of the benefits stated is the ability to report on data, which the users will not have had previously, allowing them to analyse trends (such as product sales) and enhance their business process as a result. This is an unexpected benefit, but one that will certainly intrigue the stakeholders.

We also need to give an overview of the current business processes that relate to the proposed system. If the proposed system is simply a replacement to an existing older system this is pretty simple, however if the proposed system is to add a new business process, a wide array of existing processes may need to be described here. The best way to obtain this information is to shadow an actor while they act out the existing process, discussing each stage of the process with said actor. The end result of this section could be a script or a series of actions, which can be converted in to user requirements or use cases later on.

Stakeholders and Actors

We have already briefly touched on actors; however we now need to both identify all of the stakeholders and actors that will be involved with the proposed system.

A stakeholder is a person or entity that either has an interest in or is affected by the proposed system.

An actor is a person or entity that interacts with the proposed system.

Examples of these could be:

• The CEO of the company
• The department head
• Individual users
• Third-party applications
• Interacting companies

When discussing individual system users as actors, the names of specific people are generally irrelevant. The roles within the proposed system are the actors, for example:

• Basic User (does not have access to financial information, but can create purchase orders)
• Reporting User (has view access on all areas, but cannot create purchase orders)
• Administrator (has full access)

If the company is small enough, individual users can be named here, however doing so may result in conflicting views on internal politics and positions such as:

Joe Bloggs is only a basic user, but he maintains the finance records too so we want him to be defined as one of our main actors.

This is a major hindrance to the definition of user requirements and should be avoided.

Software Requirements Specification (SRS)

This section will generally form the main bulk of a requirements document, or even be a document of its own (if the scope of the project warrants it). The idea here is to give the reader a complete definition of what is needed from the proposed system(s), in terms of the current uses, constraints, dependencies, limitations and interface needs.

Below is a quick overview of each main section included in the example document.

User Requirements / Use Cases

Some people view these as different entities; however I find that any User Requirement can be defined as a Use Case. A Use Case can be used to define a particular activity within the business, including actor interaction and processing activities. Commonly Use Cases contain the following information:

• Title / Description (what is it?) and Reference Number
• Version History (when was it written, who was it written by and if applicable when and why was it altered?)
• Actors Involved / Stakeholders Affected (who is this relevant to?)
• Goal (what are we trying to do and why are we trying to do it?)
• Triggers (where is this started?)
• Alternative Paths (where else can we achieve this?)
• Actions / Course of Events (how is the goal achieved?)
• Post-Conditions (what happens when the process is complete?)
• Business Rules (are there any policies that should be adhered to here?)
• Additional Information (has anything been missed?)

Below is a short example of a Use Case for writing a blog article:

Each Use Case can contain as much or as little information as required, for instance in the example document provided, I have omitted a number of these sections as they are not relevant to the particular situation (such as the version history and actors).

Constraints

Any restrictions on hardware, software, budget, policy, and so on must be defined here. The items described here will have a direct impact on the design of the proposed system. For example the budget may only cover the cost of existing licenses, so the readily available software must be incorporated in to the system design.

Assumptions and Dependencies

When designing the system, a certain number of assumptions must be made surrounding either the system setup, the ability of each individual user, user access rights, network activity, accompanying software and so on. The most common assumption to be made is that all users are computer literate, meaning that ‘F1 Help’ articles on ‘How To Open the Application’ can be omitted. Other assumptions could include:

• Users have access to a network share
• Internet connectivity is available
• Network speed is at least 50mb/s

A dependency is essentially a requirement of the client. For example if the project involves the creation of a website, one dependency is internet connectivity. If these are assumed and not recorded as dependencies, the development process will encounter difficulties further down the line.

Limitations

Any time the client says “leave that out”, add it to this section. In the example document, one main limitation is that despite monetary transactions being recorded, business tax is not factored in to the finances. If this is not recorded at this stage, it will only lead to feature creep during the design or even development stage.

Feature creep is the introduction of additional elements to the proposed system that were not previously specified in the original requirements, adding unnecessary cost (financially and in duration) to the end product. This section is all about the prevention of easily avoidable feature creep.

External Interface Requirements

There are normally three main areas to this section (examples included below):

1. User Interface

Examples Include: validation, colour blindness or visual impairments, training, flexibility, customisation, content presentation, page navigation, etc.

2. Hardware Interface

Examples Include: local hardware, network hardware, peripherals (scanners, barcode readers, printers etc.), maximum monitor resolution, etc.

3. Software Interface

Examples Include: database servers, operating systems, integrated applications, etc.

The purpose here is to pin down any specific requirements to each interface, and identify how the proposed system will link to other systems. The interaction between the proposed system and each external interface should be described, and any constraints, assumptions, dependencies and limitations should also be defined for each interface.

Software System Attributes

The final part of the SRS defines the non-functional requirements of the system to be evaluated following the implementation phase. The subsections that appear in the example document are:

• Reliability
• Performance
• Availability
• Security
• Maintainability
• Database Requirements

In addition to these, we could add portability of the system, ease of changeover, and any other non-functional requirements.

Contract-Style Requirements

Although contract-style requirements lists can be very extensive, if the context is well defined and each requirement is marked with a business priority or severity level, these can be very beneficial in moving forward with the requirements gathering phase. If done right, these can be a good basis for the system design, and a great comparison following implementation. However it is easy to fall in to the trap of reeling off hundreds of trivial elements, hiding in the important issues.

In the supplied example, these requirements are broken down in to a number of sections identified following the analysis of the use cases, giving a coherent and structured approach to each section. Following this, each requirement has been given a priority supplied by the stakeholders. Finally, a points system is assigned to the priority levels, giving us the ability to quantifiably prove the progress of the project during the development phase. For example, if all requirements for the ‘Assets’ section have been met, we can say with confidence that 7% of the requirements had been met.

Additional Resources

The following document is an example requirements document for a project currently in progress. For further information please visit the TCdev Snacks project page.

TCdev Snacks : Requirements