ALM: User Guide

It is important to remember that there is no single correct way to document requirements and other project documentation. The approach is determined by the process, the stakeholders, external requirements, and so on. You always need to consider who will consume a given document in your project, and how that document will be used.

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

Broadly, all approaches can be divided into two large groups:

• everything in one document;
• different documents for different purposes;

This approach is well known under the name "technical specification" (abbreviated TS). Its main advantage is that we write one document, then print it, and then agree and sign it with the customer. For these purposes it is convenient — everything you need is in one document, and it is checked for integrity, consistency, completeness, and so on.

The problem, however, is that there is no single format for creating a technical specification (or a particular technical specification). The community has developed several variants for different classes of software products or hardware-software systems. At the level of government regulation there are also several standards for documenting technical specifications. When large systems are developed, there is so much functionality that working with a technical specification alone becomes extremely inconvenient.

We recommend free-form creation of a technical specification (with no standard behind it) only in simple cases (development of uncomplicated mobile applications, websites, utilities, and other relatively simple applications).

An alternative approach is to choose a document format for different types of requirements. One format is used to record business requirements, another to record system requirements, and a third to describe the design of the software system.

In this case, different roles work with their own packages of documents, intended specifically for them. But because some types of requirements are linked to others, the links between different requirement types must be created and managed. This is exactly what a requirements management system (RMS) helps with.

Requirements of different types are linked to each other by Traces (cause-and-effect links). Traces are used to control integrity and completeness, and when analyzing the impact of changes.

For a verbal (text) description of business requirements, the best fit is documents such as Business Requirements Document (BRD) or a business case. As a rule, such documents contain a description of business processes, their time characteristics, the transfer or transformation of work products, the roles involved, and a description of cause-and-effect links.

An alternative way to describe such requirements is to use modeling languages, for example BPMN, IDEF, and so on.

A good practice is to trace business requirements (or system requirements) to the goals for which these requirements need to be implemented. Information about the goals can be contained in documents, in one of the sections. In ALM, however, it is better to use the function tree for this, where business goals sit at the top level and large system functions, business functions, or product features sit at the lower levels.

The Rational Unified Process framework offers a form for recording system requirements (functional and non-functional) in specification form, the so-called SRS:

Keep the use cases for each subsystem in a separate document. If the use cases (Use Cases) are complex and large, decompose them into component parts (slices, extensions, alternative scenarios).

Low-level requirements (system architecture and design) are conveniently recorded in the "4+1" format proposed by Philippe Kruchten, or similarly in the SAD format (Software Architecture Document, RUP).

In this approach we combine requirements of different types in one document, thereby providing better clarity and simpler documentation and management of requirements. In this approach we use the advantages of a single document and of requirement typing.

For example, in one document we can collect functional requirements (in the Use Case format) and design requirements, that is, system requirements (in the UML model format):

When developing integration solutions, or when interaction (contracts) between several components or systems must be described, the problem of controlling the integrity of the contract arises. For example, one of the systems changes its programming interface (contract), while the consumer systems that used it may remain unchanged. In the best case, such an error will be found during integration testing, and in the worst case during production operation.

To keep the error from reaching testing at all, system requirements can help if they are linked so that the consumer's requirement to maintain the contract is derived from the requirement that describes that contract (the system that provides the contract). In this case, when the contract requirement is modified, ALM marks all derived requirements (and there may be a dozen such systems) with the "Outdated" flag. All potential mismatches can be taken into account, and Enhancements of the consumer systems can be planned for the new version of the programming interface (contract).

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