Working with requirements documents

Whitepaper

www.lva.ro 2012

Intro
The total or partial outsourcing of IT services is attracting more and more all types of companies. This model allows them to have the IT resources needed to develop their business without having to invest heavily in hardware and software infrastructure. Before outsourcing, the company must reflect on what she expects from a partner. The company must know precisely what is expected of outsourcing and what the return on investment they can anticipate is. The analysis of the current situation and of the existing requirements, the specification of functional characteristics, and sometimes the legal framework are all aspects that must be mastered for a successful project. A well-researched and defined requirements document is a prerequisite for any IT project. Hence the importance of making a clear and detailed requirements document with the supplier. It is essential to draw up a complete inventory of what will be outsourced and to clearly specify the requirements.

What is a requirements document?

The requirements document is a document expressing the need of the customer, the functions of the future software and the constraints to which it is subjected. Its main role is to define the needs of the customer and what will be the use of the final product. In addition, the requirements document is a tool which facilitates the communication and information between the client and the service provider.

Why develop a requirements document?

The requirements document has three different roles. First, it describes the service that is expected. It also contributes to defining the criteria used for selecting the provider. When an external provider is the supplier, the content of the requirements document is incorporated into the contract. The commitment to achieving the technical specifications, on schedule, becomes thereby mandatory.

Finally, the requirements document will form the framework to monitor and assess the correlation between the performed activities and the needs of the customer. The requirements document is an essential framework to:

lay the foundation for the project's success: a clear definition of needs, objectives, users, etc;

obtain a guideline for the project and reduce the risk of misunderstandings; having a means of validating the project step by step; estimate the workload required for the project (commercial offers, budget and deadlines).

Four objectives of requirements document:

Define the objectives to be achieved Identify the mandatory constraints to be respected Be a tool for dialogue between partners Reduce the risk of error during the development and implementation stages.

What it includes?
The requirements document defines the functional scope of the application to be developed, that is to say, the full list of features and their description. There is no ready to use template. Its structure, accuracy and length depend on the size and purpose of the project. The idea is to get a basic structure which helps the provider understand what is expected of him. Below you will find an example of a possible structure for a requirements document. The compliance with this structure is not mandatory, but the requirements document should contain the following information: 1. Introduction. The introduction presents the product to be made in terms of needs (what will it be used for) and briefly describes its main functions. This section also allows you to present any notations used in this document as well as the table of contents.

2. Equipment. This section allows you to describe the physical resources used during the project (eg. some devices), as well as interfaces. 3.Conceptual model. The conceptual model provides an overview of the software to be created. 4.Functional needs. Functional specifications describe the functions (or operations) that the software must perform. Each function is described in detail, specifying its inputs and outputs. Here it is important not to forget to specify the legal values for inputs, and the behavior of the program for illegal ones. Do not forget to specify the behavior of the software in case of internal problems (eg. failure of the database management system, etc.). It is advisable to have a detailed presentation of each screen composing the user interface. 5. Non-functional requirements. Non-functional specifications are those requirements that do not refer to a function of the software. These specifications, expressing constraints, are basically of two types:
The constraints of the user interface. We can distinguish here the constraints imposed by the software environment (eg, the web application must run under a certain application server, the user interface should run properly on a certain browser), by physical environment (eg, the program must use the characteristics of a certain terminal) or the human environment (eg, commands must satisfy a particular constraint);

The key elements of a requirements document

Analysis of the current Project overview situation The goal analysis The needs analysis Definition of the projects objective Description Functional characteristics Defining the procedure Division into phases of work

performance constraints. There are, for example, constraints related to response time, security constraints, etc.

6. Subset and priorities for implementation. This section allows you to define any specific software versions, versions corresponding to subsets of the requirements described in paragraphs 3, 4 and 5. Sometimes it may be useful to develop certain parts of the software first. This section provides, among other things, an order in the execution of tasks.

7. Maintenance information. It is possible that, once the software is running, some parts are more likely to change than others (evolution of the material, changing user needs etc.). Specifying this from the beginning in the requirements document may help to build the software in a way which facilitates its development. 8. Glossary. The glossary contains definitions of technical terms used in the requirements document. It should assume no technical knowledge from the part of the client to whom the document is addressed. 9. Index. The index must facilitate the use of the requirements document. It is advisable to highlight graphically (eg by putting in bold) important references to a term, its definition by example.

Conclusion
A good requirements document is the reflection of understanding and mutual respect. The specification doesnt have to dictate the provider how he should carry out the project but it needs to describe the software purpose and key features. A good requirements document serve as a tool for communication between the client and the provider, and defines their mutual commitments.Its quality lies in the clarity and relevance of its content. A requirements document is the written expression of a compromise between the needs and the goal of the software and its technical and financial feasibility, based on mutual agreement between the client and the provider.In addition, it is advisable to attach to the requirements document a preliminary version of the user manual. The user manual often allows the client to verify that the product will be built according to its requirements.The manual can also help to set in detail the behavior of the software in the case of wrong input data or commands.

The key to success of any IT project is a well done requirements document, complete and consistent.