On the quality of requirements in IT projects, to be honest (from the standpoint of the development team). Part 2

Part 1 can be found by clicking on the link.

Recommendations for designing requirements specifications with examples

What they don’t say, everyone understands in his own way

As it was announced in the previous sections, we will try to convert the requirements for software development into such a format so that they maximally simplify and speed up the work of the team that turns them into the final product.

We prepare readers to get acquainted with the specifications

So, where can the introduction team start, with the requirements presented? Certainly with the presentation of the analyst of his creation, the future performers. For both sides, it is very important how well the first contact is established and the barrier to entry into the new process is overcome. But often, for several reasons, it is impossible or problematic to do it internally. Therefore, it is good practice to include a section at the beginning of the document, with a brief overview of its structure and presentation of information, as well as an explanation of how to properly and effectively use it.
')
Sample document review:



For a better perception of the context of the system being developed, in addition to the sections we selected in the structure of the document - as mandatory, I try to include in the text information about the goals that should be achieved as a result of the development of the target product or its component module. Developers still need to realize what the customer wants to get at the output of the project. For the description of this section the formalized requirements of the customer will be suitable. A similar section is in most standards, for example in GOST-34.602-89 [4] it is called “the purpose and purpose of creating (developing) a system”.

It may look like this:



When developing subsequent document artifacts, they should contain references to the User Requirements recorded in the section discussed above (since each need has its own identifier). Thus, we will be able to make sure that all the goals that the target product of the project must satisfy can be fulfilled during its implementation.

Visualize the component structure of the target product.

The main problem of large-scale projects is the need to use a large number of components. This fact can significantly impede a single representation in the imagination of the team members of the entire picture of the product as a whole. To combat this evil, I try to add a section to the beginning of the document describing the overall component architecture of the target product. This section helps to present on one (or several) images all the main nodal elements of the target product, as well as to get acquainted with the description of the ways and modes of their interaction with each other.

In his work “The Unified Software Development Process” [5], Aivar Jakobson gave the term Architecture the definition: “this is a representation of the entire project, highlighting important characteristics and obscuring the details”.
To the place of the central element of this section, in my opinion, the architecture diagram notation ideally fits. This type of presentation is similar to the canonical diagram of components, but it looks more clearly and is accessible for understanding by a wide range of specialists.

Below is a fragment of the inclusion in the requirements section with a description of the system architecture.



Such large schematic drawings are preferably accompanied by text that helps readers understand them.



Such a presentation is especially useful when several teams participate in a project. They can clearly define the points (interfaces) of contact between the components of the system, as well as their own (teams) interaction. Understanding the overall model will allow in the early stages to avoid “sagging” of the responsibility of performers in adjacent areas of work.

If the document does not consider the entire system, but only a part of it, then this part can be highlighted in the diagram in color. Thus, the same component architecture diagram can be repeated in different documents, but with different parts (components) highlighted in color.

Imagine the target product in dynamics

When we introduced the audience to the general needs of the customer and visualized the architecture of the product being developed, the reader already has an idea of ​​its main functions and the structure of building the system as a whole. Now you can proceed to a more detailed acquaintance with the main scenarios of its use. In GOST-34.602-89 [4], this section is called “requirements for functions (tasks) performed by the system”.

Often, when designing such sections, the following diagrams are used in the requirements: Use cases (UseCase) or Business Process Descriptions (BPMN), or Execution Algorithms (Activity), or IDEF0 functional models, etc. All these types of diagrams are indispensable at the design stage, the definition of the project framework, etc. But from my experience, they are of little use for programmers. From the point of view of the developers for whom this document is intended, it is much more comfortable to work with the use cases of the designed system, presented in the form of a structured text description. Summarizing all of the above in this paragraph, I note: do not overload this section with information that no one uses, but will scroll past each time to get to the desired section.

Below is a variant of the description of scenarios, which I often use in practice. The main criteria for the development of this approach were:

• The participants working with the description have no special training and cannot read the notation freely;
• Readers should describe clearly and fully all the actions that will be performed by users using the target product (module, subsystem, etc.);
• It is necessary to structure and present information using the techniques of best practices for describing processes;

Such scenarios help developers in the future, in the process of implementing static objects and system components, to quickly clarify the dynamics of their interaction. Therefore, further, in the description of Entities, Forms, Procedures, etc. References to scenarios in which they are involved must be used (the scripts, like all other specification objects, we have identifiers for).

The same scenarios can serve as the basis for the work of another group of consumers of requirements - QA specialists, since they are very close in form to testing scenarios.

DETERMINING THE COMPOSITION AND FORM OF SPECIFICATIONS OF REQUIREMENTS

Requirements specifications are not a solution kit, but a consistent action plan.

Now that all the introductory sections have been prepared, we can proceed to the formation of a key part of the document - specifications of functional requirements, which will serve as the starting point for the formation of tasks for developers.

Specifications should be grouped and well structured as blocks of information. The unit of the lowest level must be an atomic requirement, ready for transmission to the developer as a task. Therefore, each Specification should contain information sufficient for the developer to be able to unambiguously and fully implement the requirement without seeking clarification and clarification from the author. Such an approach will allow the project manager, having run through the specifications, without particularly straining, to form a set of “blanks” from them to make a detailed project schedule. Well, more on that later.

Let's start with the repository

As we agreed in the process of defining the structure and order of the specifications, the implementation phase of the requirements developers should begin with the formation of a data warehouse. Therefore, in my version of the specifications, I devote the first section to this topic. At the beginning of the section, for a more complete understanding of the domain model, it is desirable to present a general data structure. This can be done using a class diagram, it is quite popular and known to most IT professionals. The image will allow developers to contemplate the entire structure at once. The next step is to detail the specifications for each individual Entity that is used in the module.

The following is an example of specifications for the project in question:





Thus, developers who have received such requirements can only be translated into code for generating Database objects (hereinafter referred to as DB). To perform such operations, you can attract specialists with low qualifications and save the project budget.

I recommend dividing the module (system) into subsystems so that in each of them the reader operates with the number of realizable entities from 3 to 7. This allows: firstly, it is easier to perceive the material, and secondly, to simultaneously develop the module - to several developers (each separate subsystem).

A similar section is in GOST-34.602-89 [4] and it is called “Description of the organization of the information base”.

From data storage let's take a step to display them on visual forms.

After describing all the Entities that need to be implemented in this module (subsystem), you can begin to develop visual forms. Requirements for forms convenient to make out in the same style. When describing it is important to rely on the visual components of the user interface provided by the platform on which the development is being conducted. When describing forms, it is necessary to indicate which database elements described in the previous section are used to visually represent attributes (since they also have identifiers). And in order for developers to more fully represent what they are developing and how it will all move on the screen, in the description of the form we should mention the scenarios in which this form is used, without forgetting to specify the link.





Notice that for complex attributes (for example, [UI1.2.2.a9]), the table immediately describes the references to the entity with which it is associated, restrictions for selecting data, fields for displaying on the form, rules for following links on the form, and so on. d. For each attribute, a representation is indicated corresponding to the visual components of the system. With such a detailed and unambiguous description, developers can easily implement user interface requirements in a timely manner with predictable quality. In-depth detailing also makes it possible to involve less qualified personnel in the work and helps the project manager to effectively distribute tasks in the team, increasing the profitability of the project as a whole.

Give the visual form of behavior

After the visual forms are specified, you can begin programming their behavior. Therefore, in the next section, I usually present all the procedures that can be performed automatically when processing form events or are initiated by the user when working with GUI elements (buttons, menus, etc.).

For ease of use, each Requirement Specification must be assigned a unique identifier. These identifiers can be used as references, both in the requirements themselves and in other project artifacts, including diagrams. The variant of the description of actions, in particular the algorithm for generating an identifier, can be viewed in the example of requirements below.



If the module uses complex functions involving the description of volumetric algorithms, the definition of incoming and outgoing parameters, the development of an additional data storage structure, etc., then I include in the document a separate section with requirements for auxiliary functions. It can be referenced by specifications describing the actions for the forms discussed above. For example, it is convenient to use an auxiliary function when the same basic function is called during events of different forms. A similar section is in GOST-34.602-89 [4] and it is called “Algorithm Description”.

The following is an example of a similar presentation:



Further in the document sections on: Reports, Periodic Tasks, Advanced Search, etc. can optionally follow. It is advisable to fill these items with the same level of detail as shown in the examples above, indicating references to the entities, procedures, etc. used.

We take care of safety

Another important section that should be mentioned in the document for this kind of systems is devoted to access rights. It identifies Roles, describes them, and then specifies the access rights for these roles to data objects and user interface elements.

The following is an example of the requirements for the rights management subsystem:



Notice, in the example of the role table above, there is no description of the goals of the stakeholders, etc. These details are important for the analyst at the stage of forming requirements, but they are practically useless for developers. The next step, for the convenience of perception, you can create a table in the cells of which the allowed actions for the roles listed as columns will be fixed to the existing ones: procedures, database tables, user interface elements, etc., specified as rows. And permitted actions can be denoted, for example, in the form of the first letters of English words (C-Create, R-Read, W-Write, etc.)





A similar subsection is, for example, in GOST-34.602-89 [4] and it is called the “requirements for the protection of information from unauthorized access.”

In the final part, I will show examples of effective use of such specifications of requirements, PM and QA specialists link .
.