Requirements and Specifications

The Importance of Requirements and Specifications

Behind any concerted effort to build, launch, or maintain a web site is probably an idea or concept of what the site's leadership or company executives want done. Behind any rational web effort should be a formal structure and methodology known as a project plan. Project planning is a technique now common to information technology and media work (I mention project plans and planning only in passing here -- this topic deserves a deeper treatment that is beyond the scope of this particular essay).

Most web site projects include a body of information that describes the product or output of the project's work effort; this information deals with the objectives of the final product, defined in the project requirements, and any rules for creating the product, defined in the project specifications.

Requirements Define Necessary Objectives

Any coherent and reasonable project must have requirements that define what the project is ultimately supposed to do. According to Kaner et al. in Testing Computer Software

A requirement is an objective that **must** be met. Planners cast most requirements in functional terms, leaving design and implementation details to the developers. They may specify price, performance, and reliability objectives in fine detail, along with some aspects of the user interface. Sometimes, they describe their objectives more precisely than realistically (p 32).

There are actually several kinds of requirements; the term requirement is awkward because it describes the concept of an objective or goal or necessary characteristic, but at the same time the term also describes a kind of formal documentation, namely the requirements document. Putting aside the particular document for now, requirements are instructions describing what functions the software is supposed to provide, what characteristics the software is supposed to have, and what goals the software is supposed to meet or to enable users to meet.

I prefer to use the term requirements to refer to the general set of documents that describe what a project is supposed to accomplish and how the project is supposed to be created and implemented. Such a general set of requirements would include documents spelling out the various requirements for the project -- the "what" -- as well as specifications documents spelling out the rules for creating and developing the project -- the "how".

Project requirements provide an obvious tool for evaluating the quality of a project, because a final review should examine whether each requirement has been met. Unfortunately, it's never quite that easy. Requirements tend to change through the course of a project, with the result that the product as delivered may not adhere to the available requirements -- this is a constant and annoying facet to the quality assurance process. Moreover, meeting all of the requirements doesn't ensure a quality product, per se, since the requirements may not have been defined with an eye towards the quality of the end-user's experience. A project's specifications are more useful for determining the product's quality.

Specifications Define How to Meet The Objectives

A specification is literally the discussion of a specific point or issue; it's hard in this instance to avoid the circular reference. A project's specifications consist of the body of information that should guide the project developers, engineers, and designers through the work of creating the software.

A specification document describes how something is supposed to be done. This document may be very detailed, defining the minutia of the implementation; for example, a specifications document may list out all of the possible error states for a certain form, along with all of the error messages that should be displayed to the user. The specifications may describe the steps of any functional interaction, and the order in which they should be followed by the user. A requirements document, on the other hand, would state that the software must handle error states reasonably and effectively, and provide explicit feedback to the users. The specifications show how to meet this requirement.

Specifications may take several forms. They can be a straightforward listing of functional attributes, they can be diagrams or schematics of functional relationships or flow logic, or they can occupy some middle ground. Specifications can also be in the form of prototypes, mockups, and models.

Project specifications are much more important for determining the quality of the product. Every rule and functional relationship provides a test point. Adherence to specification is not a perfect measure, however. Again according to Kaner et al.,

A mismatch between the program and its specification is an error in the program if and only if the specification exists and is correct. A program that follows a terrible specification perfectly is terrible, not perfect (p 60).

A critical part of the quality assurance role is proactive involvement during the project requirements analysis and specification phases, where the rational and customer-centered point of view of the QA analyst can be applied to the project's rules before any code is written. The return on investment (ROI) of this up-front QA involvement has been shown to pay off: several studies have determined (and common sense supports) that companies will have to pay less to fix problems that are found early in any project cycle. Catching problems when the requirements and specifications are being hammered out is the ideal time to head off problems.

Kaner et al. list 6 test points to be covered when reviewing requirements and specifications, described here briefly:

+ Are these the "right" requirements? + Are they complete? + Are they compatible? + Are they achievable? + Are they reasonable? + Are they testable?

Examples of Requirements and Specifications Documentation

The following list describes the various kinds formal documents that belong to the body of requirements and specifications document. These are not all mandatory for each and every software project, but they do all provide important information to the developers, designers and engineers tasked with implementing a project and to the quality assurance people and testers responsible for evaluating the implementation of the project. These topics may also be combined as sections of larger and inclusive requirements and specifications documents.

User Requirements

User requirements typically describe the needs, goals, and tasks of the user. I say "typically" here because often these user requirements don't reflect the actual person who will be using the software; projects are often tailored to the needs of the project requestor, and not the end-user of the software. I strongly recommend that any user requirements document define and describe the end-user, and that any measurements of quality or success be taken with respect to that end-user.

User requirements are usually defined after the completion of task analysis, the examination of the tasks and goals of the end-user.

System Requirements

The term system requirements has two meanings. First, it can refer to the requirements that describe the capabilities of the system with which, through which, and on which the product will function. For example, the web site may need to run on a dual processor box, and may need to have the latest brandX database software.

Second, it can refer to the requirements that describe the product itself, with the meaning that the product is a system. This second meaning is used by the authors of Constructing Superior Software (part of the Software Quality Institute Series):

There are two categories of system requirements. **Functional requirements** specify what the system must do. **User requirements** specify the acceptable level of user performance and satisfaction with the system (p 64).

For this second meaning, I prefer to use the more general term "requirements and specifications" over the more opaque "system requirements".

Functional Requirements

Functional requirements describe what the software or web site is supposed to do by defining functions and high-level logic.

In many cases, if the user requirements are written for the requestor and not the end-user, the functional requirements are combined with the functional requirements; this is common within companies that have a strong Information Technology department that is tasked with doing the work.

Functional Specifications

Functional specifications describe the necessary functions at the level of units and components; these specifications are typically used to build the system exclusive of the user interface.

With respect to a web site, a unit is the design for a specific page or category of page, and the functional specification would detail the functional elements of that page or page type. For example, the design for the page may require the following functions: email submission form, search form, context-sensitive navigation elements, logic to drop and/or read a client-side cookie, etc. These aren't "look" issues so much as they are "functionality" issues. A component is a set of page states or closely related forms of a page. For example, a component might include a page that has a submission form, the acknowledgement page (i.e., "thanks for submitting"), and the various error states (i.e., "you must include your email address", "you must fill in all required fields", etc.).

The functional specifications document might have implications about the design of the user interface, but these implications are typically superceded by a formal design specification and/or prototype.

Design Specifications

The design specifications address the "look and feel" of the interface, with rules for the display of global and particular elements.

Flow or Logic Diagram

Flow diagrams define the end-user's paths throng the site and site functionality. A flow diagram for a commerce site would detail the sequence of pages necessary to gather the information required by the commerce application in order to complete an order.

Logic diagrams describe the order that logic decisions are made during the transmission, gathering, or testing of data. So for example, upon submission of a form, information may be reviewed by the system for field completeness before being reviewed for algorithmic accuracy; in other words, the system may verify that required fields have in fact been completed before verifying that the format of the email address is correct or the credit card number is an algorithmically valid number. Another example would be the logic applied to a search query, detailing the steps involved in the query cleanup and expansion, and the application of Boolean operators.

System Architecture Diagram

A system architecture diagram illustrates the way the system hardware and software must be configured, and the way the database tables should be defined and laid out.

Prototypes and Mock-ups

A prototype is a model of the system delivered in the medium of the system. For example, a web site prototype would be delivered as a web site, using the standard web protocols, so that it could be interacted with in the same medium as the project's product. Prototypes don't have to be fully functioning, they merely have to be illustrative of what the product should look and feel like. In contrast, a mock-up is a representation in a different medium. A web site mock-up might be a paper representation of what the pages should look like.

The authors of Constructing Superior Software describe several categories of prototypes: low fidelity prototypes which correspond to what I've labeled "mock-ups", and high fidelity prototypes.

Low fidelity prototypes are limited function and limited interaction prototypes. They are constructed to depict concepts, design alternatives, and screen layouts rather than to model the user interaction with the system....There are two forms of low fidelity prototype: abstract and concrete....The visual designer works from the abstract prototype and produces drawings of the interface as a concrete low fidelity prototype....High fidelity prototypes are fully interactive (p 70-71).

Prototypes and mock-ups are important tools for defining the visual design, but they can be problematic from a quality assurance and testing point of view because they are a representation of a designer's idea of what the product should look and feel like. The issue is not that the designer's may design incorrectly, but that the prototype or mock-up will become the de facto design by virtue of being a representation. The danger is that the design will become final before it has been approved; this is known as "premature concretization" or "premature crispness of representation", where a sample becomes the final design without a formal decision. If you have every tried to get page element removed from a design, you have an idea what this problem is like. The value of prototypes is that they provide a visual dimension to the written requirements and specifications; they are both a proof of concept and the designers' sketchpad wrapped up in one package.

Technical Specifications

Technical specifications are typically written the by developers and coders, and describe how they will implement the project. The developers work from the functional specifications, and translate the functions into their actual coding practices and methodologies.