ALM User's Guide

It's important to remember that there is no one right way to document requirements and other project documentation. The approach used is defined by a process, stakeholders, external requirements, etc. You should always take into account consumer of each document in your project, as well as the use of this document.

We collect best practices of creating project documentation and, in particular, documenting requirements and share them with you.

Relatively speaking, all approaches can be divided into two big groups:

• all requirements in a single document;
• different documents for different purposes;

This approach is well-known and called "Technical specification" (TS). Its main benefit is that we prepare one document, print it, then reconciliate and sign it with customer. The approach is convenient for these purpose - you get all the content in one document, this document is checked for integrity, consistency, completeness, and so on.

However, the problem is that there is no one single form to create technical specification (or component technical specification). The community has developed several options for different classes of software products and software and hardware systems. There are several standards for documenting technical specification on the level of government regulation. When developing a large system, there are so many features to implement, and it becomes very inconvenient to work with a single technical specification.

We recommend to create a technical specification in the free form (without any standard) only for simple cases (development of simple mobile applications, web sites, utilities, and other relatively simple applications).

You can find a template of technical specification based on GOST 34 in the project that was created based on Waterfall template.

This standard offers 6 options (or perspectives) of documenting requirements: regarding events, incentives, roles, and functions. Choose the most convenient perspective for a particular task and consumers.

Alternative approach is to select the document format for different types of requirements. One format is used to commit business requirements, another format - to commit system requirements, and third format - to describe the design of software system.

In this case, different roles work with their document suites intended specifically for them. Since some types of requirements are connected with the other types, it's necessary to form relationships between different types of requirements and control them. Requirements control system (RCS) is designed to perform this task.

Requirements of different types are interconnected with each other by traces (causal relationships). Traces are used to control integrity, completeness, as well as to analyze the change impact.

Business Requirements Document (BRD) or Business case are the best choice if you want to describe business requirements verbally (by text). As a rule, such documents contain description of business processes and their time characteristics, transmission or transformation of working products, involved roles and description of causal relationships.

Alternative approach is to describe such items is to use modeling languages, e.g., BPMN, IDEF, etc.

A good practice is to trace business requirements (or system requirements) to goals which are achieved by means of implementation of these requirements. Information about the goals may be contained in one of the documents’ section. However, in Devprom ALM, it's better to use a function tree where business requirements are located at the top level, and major system functions, business functions or product features are located at the bottom levels.

Rational Unified Process framework offers a format for storing system requirements (functional and non-functional) in the form of specification called SRS:

Store use cases for each subsystem into a separate document. If use cases are big and complex, decompose them into pars (slices, extensions, alternative cases).

Low-level requirements (system architecture, design) can be easily stored in the "4+1" format offered by P. Kruchten, or similarly in the SAD format (Software Architecture Document, RUP).

In this approach, we combine requirements of different types in a single document thus providing better visibility and more simple documenting and manageability of requirements. In this approach we use benefits of a single document and requirement typing.

For example, we can combine functional requirements (in the form of use cases), as well as design requirements, i.e. system requirements (in the form of UML model) in a single document:

When developing integration solutions, or describing interaction (contracts) between several components or systems, the task of contract integrity control appears. For example, one system changes its software interface (contract), and systems-consumers that used it may be left unchanged. At best, such error will be identified during the integration testing stage, at worst - during the production stage.

To remove this error prior to the testing stage, you can use system requirements related in such a way that consumer's requirement to maintain a contract will derive from a requirement describing this contract (system-contract provider). In this case, after modification of contract requirement Devprom ALM will mark all derived requirements (there can be dozens of such systems) by "Obsolete” flag. Thus, you can take into account all potential inconsistencies and plan the enhancement of systems-consumers for a new version of software interface (contract).

And, of course, such requirements can be placed in different projects.