ALM: User Guide

Depending on the project conditions, the complexity of the product, the professionalism of the team, and many other factors, different approaches to working with requirements are used.

When implementing simple and clear requirements, it is not necessary to create detailed specifications or to document business processes. Working with documentation takes time, especially when requirements change continuously. For throwaway products, prototypes, and an MVP, upfront design is less valuable than the speed of feedback from users.

In this case, development relies on primary (user) requirements. The customer or their representatives formulate requirements and clarify them together with the project Participants. Once the requirements are clear, the team implements them and, as a working product, hands them to the customer's users so that feedback can be formed. The cycle then repeats until all user tasks have been completed.

User Stories are one of the convenient and widely used ways to record user requirements. In short, a User Story is written in the following format:

Brevity is good, but project success depends on the quality of the requirements. Use the principles INVEST, as a checklist for checking the quality of the Stories that have been written.

Do not confuse a description of functional requirements in the Use Case format with user requirements in the User Story format — these are two very different views of software requirements. One User Story can contain several Use Cases. User Stories are not a way to structure software requirements.

Identification

You can define your own scheme for identifying artifacts, different from the one used in the system by default. To do this, open the settings of the "UID" attribute and set a formula there for calculating the default value.

As the formula for calculating the Requirement identifier, write an expression following the example from the description. Here are several variants of custom identification of Requirements:

• {PageType.ShortCaption,R}.{Id} - the Requirement ID starts with the short name of its type, for example, SR.123
• {PageType.ShortCaption,R}-{IdProject} - the "IdProject" field value is filled by an automatic counter within the project. In each project the counter starts at 1. This way you can get identifiers such as: BR-1, SR-2, and so on.
• {PageType.ShortCaption,R}-{IdType} - the "IdType" field value is filled by a counter for each Requirement type. This way you can get identifiers such as: BR-1, SR-1, and so on.
• {PageType.ShortCaption,R}-{IdHierarchy} - the "IdHierarchy" field value is filled by a counter within the hierarchy (document), that is, the counter increases for each next child element inside the document.
• {PageType.ShortCaption,R}-{IdParent} - the "IdParent" field value is filled by a counter within the parent section, that is, the counter increases for each next child element inside one section.

You can form an identifier using leading zeros; for example, given the expression {Id,6}, the system forms the identifier as 000001, 000002, and so on.

The risks of developing software from user requirements are that:

• a change in team composition can lower the level of professionalism and of knowledge about the internal structure of the system; the quality of the requirements will suffer, and as a result so will the quality of the product;
• user requirements are not a substitute for functional requirements, because they are formulated as the need arises and concern different parts of the system. After several months of product development you will have hundreds of Stories, often contradictory, that do not let you understand how the system, and a specific function of it, is supposed to work;
• implementing new requirements can break the integrity of the product and lead to the loss of important functionality, because someone decides that a particular checkbox is unnecessary.

The practice of developing supporting requirements helps reduce these risks.

Before implementing a User Story, while implementing it, or immediately afterwards, document the important technical decisions: UI mockups, algorithms, data models, and others. On the one hand, these system requirements will be linked to the Story and will let you implement it properly. On the other hand, over time you will accumulate structured system requirements for the whole product, which removes the risks described above.

Why is it a poor idea to write system requirements directly in the Story itself? A User Story is, by definition, supposed to be small. Completion criteria and acceptance criteria already enlarge its description. System requirements in the form of mockups (and detailed requirements for them), algorithms, and various models make the Story very bulky and awkward to work with. Moreover, finding the system requirements you need later becomes simply impossible, to say nothing of making changes to them.

Implementing a product from fragmentary and superficial ideas of its functionality can lead to technical decisions that are fast but short-sighted. In agile methods (Scrum, XP) this is called technical debt. Instead of doing it right the first time, you have to rework the system architecture that was laid down earlier. That is an extra loss of time and money.

The "cone of uncertainty" tells us that the less detailed the requirements are, the larger the error in estimating their complexity or effort. A more accurate estimate of the project budget, or of the budget for changes to requirements that have already been implemented, is possible only when the requirements have been worked out in advance and the impact of changes on them has been analyzed.

Development based on requirements (Requirements driven development, RDD) explicitly sets aside a design cycle, during which:

• primary requirements are collected and documented, contradictions are removed, and all necessary details are clarified;
• documentation is created at the level of business requirements and functional requirements (requirements for the product);
• requirements are agreed with architects and testers for feasibility, testability, and other quality parameters;
• requirements are agreed with the customer, the budget is estimated, and their implementation (development) is planned.

After the design cycle, a development cycle is organized on the basis of the development tasks that were created (Enhancements):

• a plan of Releases or Iterations is formed, within which portions of requirements are implemented (for example, product functions);
• the engineering cycle is carried out: low-level design, development, testing, documentation, and so on;
• executable code is created, which designers and the customer can use to accept the development results.

In some cases the project can end immediately after the design cycle, if the goal of the project was to develop the software requirements.

Development from requirements is sometimes confused with waterfall development (or development according to GOSTs). The volume of requirements being designed (the size of the increment) can be adjusted to the conditions of the project.

Requirements can be distributed across different projects and linked to each other:

• Shared business or functional requirements can be developed at the program level, while detailed system requirements for components are developed at the level of subprojects that manage the work of different teams;
• Shared requirements can be stored in the program, while subprojects can be used to develop functional and system requirements for desktop, mobile, and other variants of the product;
• Requirements for systems that are integrated with each other can reside in different projects and be linked, so that the impact of requirement changes in one system on the requirements of another can be tracked.