👨🏽‍💻 🥚 💓 JIRA: rules for the timely preparation of delicious software. TLDR 2: requirements management 🚊 🍴 👢

Earlier in the article “ JIRA: the rules for the timely preparation of delicious software. TLDR 1: boundaries of possibilities ”an attempt was made to unify the general requirements for the use of JIRA in the case of the management of several projects for the development of custom software in one of the departments of our company . Developing the topic, this article will be devoted to the key features of registration, clarification and monitoring of the implementation of customer requirements in the framework of the previously proposed model . Any criticism is welcome.

Source

Any finished product is determined primarily by the quality of the original ingredients, and the software is no exception ( Garbage In - Garbage Out ). If the original ingredients are slightly rotten or some of them are simply missing, you are unlikely to be able to save the situation with the help of a super-oven or a wonderful pan. In the case of software, the initial components are the good intentions (dreams) of the customer about a bright future (when “ robots are working hard, a person is happy ”).

One of the paradoxes of modern government contracts is that the contractor often has a weak influence on the process of forming requirements, i.e. real requirements analysis processon the project begins after approval of the list of these requirements. The fact that the project team’s recommendations regarding the wording of the requirements had no effect on the text of the contract, the project manager usually finds out from the joyfully excited representative of the contract department, who, with a sense of complete debt, reports that the long-awaited tender is finally won and the deal Remains small. At the same time, on the one hand, the customer in every possible way impedes the change of requirements in the approved document (a dream is sacred), and on the other hand, he can easily interpret the same requirement in different ways depending on the situation.

Under these conditions, it is desirable to ensure that all customer requirements are stored in your “digital kitchen” in such a way that, at the stage of project delivery, avoid severe frustration of all interested parties to the project.

To solve this problem, within the framework of the previously proposed approach , a special type of task is designed - the “requirement”. A list of these task requirements is formed by the so-called project backlog. In newer versions of JIRA, an analog of this type of task is the task type “epic”. However, as will be seen later, the type of tasks “requirement” in our project is not just fixing the conceptual thought forms of the customer, but tasks characterizing the results of the activities of the project manager and analysts on requirements management .

Rules for slicing requirements

If the customer receives a list of requirements for software refinement (for example, an approved terms of reference), all activities for registration and maintenance of the list of requirements in JIRA can be reduced to two border scenarios.

In the first case, the project manager simply forwards the letter with the customer’s requirements to the analysts with a note “Register the requirements regarding the tangent with JIRA and ensure their implementation”. After that, the project manager can “hammer” on the project until the start of preliminary tests (the only thing is to ensure that all requirements find their responsible executors in JIRA). If your project team consists of sane analysts, ingenious programmers, workaholic testers and technical graphomaniac writers, the result of this approach will not differ from the second, more troublesome option.

In the second case, requirements management work is divided into several stages.

Source

Start. Registration of the source document for software development / modification in JIRA. The received materials are uploaded to the repository with the number of the corresponding task indicated in the comment of the commit.

1. Based on the registered source document, a meeting is planned, the purpose of which is to determine the boundaries of responsibility for fulfilling the requirements, identifying “white spots” and “esoteric” requirements. The planning of the meeting is carried out directly in JIRA (for this, a task of the “implementation” type is registered, the person responsible for the task is the project manager, participants are registered as observers, agenda items are recorded in the description). The time spent on a preliminary analysis of requirements is independently fixed by analysts in the form of subtasks for the planned meeting. If questions arise during the analysis, they are reflected in the comments on the meeting agenda.

During the meeting, decisions are made on the appointment of those responsible for the “white spots”. Risks with respect to “esoteric” requirements are evaluated and ways to overcome them are proposed. The first, as yet very approximate, version of the “road map” is being formed, according to which the work will be organized (taking into account the priorities and current employment of the project team).

2. After the analyst has been appointed responsible for the implementation of the requirements, he registers each requirement with JIRA as a separate task related to the source document (the link “complements”). The initial status of the claim is “rating” .

One of the basic rules - each customer requirement must be registered as a separate taskat JIRA. This approach, in turn, makes it possible to assess the status of the project from the point of view of implementing each of the requirements of the customer, and not from the point of view of the number of tasks performed or the investment of labor. The wording of the requirement is recorded in the "Description" field word for word as in the customer's document.

Also, “atomic” registration of requirements subsequently makes it possible to automatically generate reporting documentation when a release or update is issued (protocol of functional composition and testing).

3. Given the developed roadmap for each of the requirements at the initial stage of its implementation, the following issues should be resolved by the responsible analyst:

clarification of the semantic content of the requirement;
clarification of the boundaries of implementation.

At the time of clarification, the requirement can be transferred to the status of “pending” , indicating the corresponding reason.
All materials for clarification (interpretation) of the requirements are attached to the corresponding task (uploaded to the documentation repository). The resulting materials should come from the customer and should allow a clear answer to the above questions. It is advisable that this be a protocol of the meeting to clarify the requirements, at least - e-mail from correspondence.
After elimination of “white spots”, the requirement can be transferred to the status of “assigned” .

4. Within the framework of the implementation of one functional area (one key use case - use case) the responsible analyst must formulate tasks of the “analysis” type related to the relevant requirements.

5. If necessary, the responsible analyst conducts an information survey of the automation object.

6. After collecting the necessary initial data for the design, the responsible analyst forms the design decision.

7. Based on the results of the design decision, the analyst must form / clarify the list of components that are subject to development / modification.

8. The developed design solution is a necessary and sufficient condition for creating tasks for the development, testing and documentation and forecasting the complexity of their implementation.

This is often where the main stumbling block between managers and developers is located. One ofThe approaches used to reduce the uncertainty in solving this issue is to evaluate the proposed task by the responsible developer, provided that the total complexity of the individual task should not exceed 16 hours. Alexei Kataev in his report convincingly shows that if the labor costs for the implementation of the task exceed 12 hours, the reliability of the forecast of the complexity of such a task becomes akin to the reliability of the forecast of gambling winnings. Therefore, to ensure the required quality of planning, it is recommended to decompose the tasks.

On the other hand, from the point of view of management, I would like to achieve a result that is significant from the point of view of the customer during the development task, which is not always achievable in 16 working hours.

In our case, it was decided that if the complexity of the task exceeds 8 hours, the author of the task should break it into separate stages (which does not always mean subtasks). Additionally, formal lists of particular results for each of these stages were determined. In addition, online calculators were created to increase the objectivity of forecasts based on these lists using the PERT method.determination of the total complexity for tasks of different types (a more detailed description of working with these tools is supposed to be given during the publication of the following articles). But at the same time, a limitation was established that the maximum projected complexity of a single JIRA task should not exceed 32 hours. In the event that the contractor does not agree with the projected complexity of his task, as an argument, he must submit his calculation of the complexity, performed using the same tools. The arbiter in resolving such disputes between the analyst responsible for the implementation of the requirement and the executors is the project manager (teamlead).

9. Immediately after the registration of requirements associated with the requirement for the development, testing and documentation, the project manager should specify the priority and timing of the implementation of this requirement (taking into account the total labor costs of the related tasks, priorities and the required deadlines for the implementation of other tasks of the project). Given these clarifications, in turn, the responsible analyst can adjust the timing of tasks for development, testing and documentation.

10. The implementation of the design solution is carried out within the framework of tasks of the “development” type.
After the first requirement-related task for software development is put to work, the requirement must be transferred to the status "in work" (this can be done using the Automation for Jira plugin ).

11. Based on the specified implementation deadlines, a decision is made to include the implementation of the requirement in one or another software release. The customer must be informed of any changes in the composition or delivery time of the release.

12. In parallel with the development process, a version of user documentation is formed on the basis of the design decision.

13. After completing development tasks, the programmer should clarify the list of components that have been developed / modified.

14. Re-clarification of user documentation should be carried out as part of an offline test. Fulfillment of all requirements related to the requirement for development, documentation and testing is a signal for translating this requirement into the status of "completed" and its inclusion in the release.

15. The revision is included in the software release in accordance with the delivery decision made by the project manager.

16. Before the tests are carried out, repeated integration testing of the implemented requirements included in the release is carried out.

17. Confirmation of the correctness of the implemented requirements can be carried out during software testing (preliminary, trial operation, acceptance). The test results are recorded in JIRA as part of the "implementation" type tasks.
After a document has been received from the customer on the correct implementation of the requirement, it can be transferred to the “closed” status . In the event that comments are received from the customer regarding the requirement, it is returned to the “assigned” status(on stage number 8). At the same time, the comments themselves can be fixed in JIRA as separate requirements related to the main requirement using the “Relates” communication type .

Let me remind you that the described scheme does not reflect the workflow of a separate task in JIRA, but involves the creation of a set of interrelated tasks of various types (which is reflected in the scheme with the corresponding colors). The given sequence gives an overview of the standard procedure for implementing new customer requirements. At the same time, this scheme does not exclude the possibility of deviations from it, for example, in the case of preliminary prototyping prior to the design decision. However, in our project, such exceptions must be agreed with the project manager.

During testing or commercial operation, customer comments on the created software will inevitably be revealed. These remarks can be conditionally divided into the following groups:

new requirements;
clarifications on implementation;
defects;
mistakes.

Despite the fact that, in accordance with the initially proposed approach, comments are recorded in JIRA as well as requirements for software refinement (as tasks of the “requirement” type), the process of their elimination deserves separate consideration.

Rules for coloring cockroaches

The one who does nothing is not mistaken.
Theodore Roosevelt

There is no software without errors. Absolutely. Even if there are no errors in the code, a sophisticated user will find them in the documentation or just come up with them. One way or another, I have not seen projects where there were no software incidents. Software Maintenance Analysis by American Institute of Software Engineering ( SEI) in the early 90's, showed that the correlation coefficient between the number of errors detected during testing of individual modules and the number of errors found by users in the finished product is 0.91. Simply put, if 10 errors were detected at the testing stage, 9 more others will appear during the trial operation. Achieving the required quality in the development of software for space stations is achieved in particular due to the tenfold superiority of the testing staff over the development staff, not including the use of advanced techniques, for example, unit testing or GUI testing automation. In my opinion, the reliability of such software is achieved due to the minimum possible involvement of live users in its work. Of course, it is very cool when a professional quality control team works on the project . However, in many software projects it is not possible to implement all these recommendations for various objective and subjective reasons.

Therefore, if the project manager does not manage the flow of incoming incidents, then very soon this thread will manage such a manager (if he does not "choke" in this thread).

On the other hand, as experience shows, a significant part of the customer’s comments that were initially classified by him as a software error is not an error. The appearance of comments of this kind may be due to such reasons as:

violation of technical operating conditions of software (“crooked hands” of customer’s system administrators);
restrictions on user access rights (assigned user access rights do not meet his expectations);
the mismatch of the functional expectations of the user with the implemented requirements (if nothing helps, maybe you should read the instructions?);
inconsistency in the description of the software implementation (a rather rare remark, since the users and administrators of the customer, as a rule, do not read the manuals after the first acquaintance with the software).

In this regard, during correspondence with the customer regarding comments on the software, it is recommended to avoid words such as “error” or “defect”, at least until it is completely unambiguously established. Up to this point, it is recommended to use the words “remark” or “incident”.

The unified process of carrying out work to eliminate incidents can be represented as a sequence of the following steps.

Source

Start. Register an incident resolution application with JIRA. This stage for different projects can be organized in its own way. You can, for example, register applications received from the customer manually with JIRA, or you can use a special mailbox, which JIRA will independently view and configure tasks based on incoming letters. If you are developing a web application, you can use the JIRA task collector to collect user comments . The field of how the comment somehow turned out to be registered in JIRA (in the status of "rating" ), it is necessary to pre-process it.

1. Clarification of the incident conditions. As part of this action, it is necessary to collect the most complete information about the software comment:

the sequence of actions during which the incident occurs, a combination of input data;
details and authority of the user of the comment;
location of the workstation (server);
screenshots of user screens;
monitoring protocols;
samples of incorrectly generated files (reports).

Often, a significant part of incidents ends their life journey at this stage, since during the collection of artifacts it turns out that the detected “error” is the standard behavior of the system. If the JIRA begins to accumulate requirements for resolving incidents that were resolved without creating development tasks, it is worth paying close attention to the user friendliness of the user interface and the relevance of the user manual.

2. Breakdown of the incident into "atomic" requirements. Often, in one letter, the customer representative may reflect several comments. Therefore, if necessary, in the second step, based on the registered letter from the customer to JIRA, separate requirements tasks are formed. In addition, each of these tasks is associated with the parent requirement using the Cloners relationship . For each of these tasks, the materials collected at the previous stage are attached (in part regarding). Further, all work is organized with each requirement separately.

3. Defining the contractual framework. After specifying the identified defects, a determination is made to what type of contractual relationship the work to eliminate it can be attributed. From the point of view of further work organization, this stage can fundamentally change the priority of further tasks. In many projects, the trial operation of new components developed as part of development is carried out by installing these components directly on the current version after a short autonomous testing. However, the customer correlates the errors that arise in these cases already with the contracts for basic or warranty support, which stipulates strict deadlines for eliminating the defects. If, within the framework of basic support, the contractual period for eliminating the defect can be measured in hours, then if the defect is identified in relation to the new functionality,the period for eliminating the same defect is determined by the end date of the trial operation (up to several months). If the project manager does not pay attention to this “small” nuance, the executing company has every chance to start paying a penalty for simple software even before it is put into commercial operation.

4. Control of duplicates. In the case of re-joining application for the removal of previously detected defects, this requirement is associated with the previously filed task via connection "Duplicate» ( Duplicate ).

Based on the results of the preliminary analysis of the incident, it is necessary to inform the customer of its results, since the customer’s vision of the timing of the elimination of the incident may weakly correlate with contractual obligations.

5. The incident should be repeated on the test server by the support team before submitting the request to the development team analyst. The initial testing can be recorded in JIRA in the form of a subtask to the relevant requirement.

6. If the incident was not resolved in the course of the previous steps, the requirement is transferred to the “assigned” status and transferred to the analyst of the development team to identify the reasons for its occurrence and formulate tasks for its elimination.

7. If necessary, the analyst must clarify the contractual scope of the requirement. If a comment is made regarding the new functionality of the software, then the analyst must associate this defect with the relevant requirements for development / development / extended support (the “Adds” link).

8. The analysis should also determine the list of components that affect this comment. In addition, if the comment is really a software bug, it must be generated.typification of the detected defect.

9. After identifying the causes of the defect, the analyst of the development group forms development tasks aimed at eliminating the identified error. If necessary, tasks for testing and clarifying documentation are formed. As part of these tasks, planned labor costs are determined. If the workload of a particular task exceeds 8 hours, it is necessary to provide a justification of the complexity using the tools specified in the previous section. Taking into account the priority and workload of the project team, the planned dates for the implementation of these tasks are determined.
After the first requirement related to the development of the software is taken to work, the incident must be transferred to the status of "in work" .

10. The appearance of related tasks for the development, testing and documentation of a requirement is a signal for the project manager to make a decision about which version of the software the identified defect will be fixed. At the same time, the project manager plans an event for the implementation of software by linking the corresponding requirements to the JIRA task of the "implementation" type.

11. If necessary, the project manager clarifies the planned dates for the implementation of related tasks and informs the customer about this.

12. Correction of the defect is carried out within the framework of tasks of the "development" type.

13. After elimination of the defect, the developer, if necessary, should clarify the type of the detected defect and the composition of the components that have been modified.

14. If necessary, the documentation is specified.

15. Specialists of the support group conduct autonomous testing of the corrected functionality (as part of the testing task formed by the analyst of the development group).
Also, as in the case of the implementation of the new requirement, the basis for transferring the incident to the status of “completed” is the fulfillment of all tasks created on its basis (with the exception of tasks of the “implementation” type).

16. After conducting offline testing, the fix is included in the update and in the current release.

17. After the readiness of all the improvements planned for inclusion in the release of the delivery, integration testing is carried out. Conducting integration testing can be fixed in JIRA in the form of a sub-task for the corresponding task of the "implementation" type.

18. Software updates are transmitted to the customer in the established manner. However, the transfer of tasks of the relevant requirements to the status of "closed" is possible only after receiving from the customer documentary evidence of the elimination of the incident.

Source

Any developer knows that the biggest mistakes are those that were not detected in a timely manner at the stage of formation / specification of requirements.

Requirement Freezing Rules

Walking on water and developing software according to the specification is very simple when both are frozen.
Edward V. Berard

It should be noted that the clarification of requirements most effectively has proven itself by creating a situation where the customer needs to give a simple answer to the clarifying letter: “I agree”. For this, it is necessary to formulate several possible answers in the letter . The art of forming such letters is that the very option that the customer chooses is most preferable for you as a performer.

Source

For example, the “simple” requirement “to provide the possibility of sampling by region in all screens” at the delivery stage can cause many problems, since it does not determine on which screen forms the sampling should be provided, whether sampling by one parameter value or several how the historicity of changes in the name of regions should be taken into account. If you just ask to clarify this requirement, it is unlikely that the answer will solve the indicated problems.

In this case, clarification can be made using a letter of the following contents:

. 4.5.6. : « 1, 2 3 «». , , ».

A copy of the letter is attached to the task. The task is transferred to the “pending” status until a response from the customer is received, which is also subsequently attached to the task. This wording is reflected in the corresponding field of the JIRA task (see below, “Clarification”). It is on its basis that related design decisions, development tasks and test tasks are formed.

Ideally, which is often achievable as a horizon for objective and subjective reasons, in order to transfer the requirement to further development, it is necessary to ensure an understanding of its boundaries by all members of the project team. Therefore, as soon as a task of the “requirement” type is associated with development tasks, the project manager checks that he meets the quality criteria described below ( Definition of Ready) If the basic wording of the requirement does not meet these criteria, the work on its refinement must be carried out without fail. The result of the refinement work should be either an updated wording of the requirement, or a design decision (SCF) agreed by the customer related to this requirement.

Criteria for assessing the quality of requirements on a project
Characteristic	Explanation
Completion	The requirement is fully defined in the JIRA task, and all necessary information is present.
Consistency	The requirement does not contradict other requirements and complies with regulatory documentation.
Atomicity	The requirement is “atomic”. That is, it cannot be broken down into a number of more detailed requirements without loss of completeness.
Relevance	The requirement has not become obsolete over time.
Feasibility	The requirement can be implemented within the project (taking into account available resources and timelines).
Unambiguity	The requirement is briefly defined without resorting to technical jargon, acronyms, and other hidden phrases. One and only one interpretation is possible. The definition does not contain ambiguous phrases. The wording of the requirement (clarification) does not contain negative and compound statements.

When accounting for labor costs in a task of the type “requirement”, only the time spent directly on its refinement is recorded. All other labor costs are recorded in tasks of the corresponding types (or their subtasks).

In addition to the common attributes described in the previous article , a set of additional attributes was defined for each task of the “requirement” type in JIRA during a long and painful process.

«»


*	( ).
	: ( , , .. ); ; — ( , , ); ; ( , ); /; (, , , , , ).
	, (, ).
()	. , , ( ).
	– . . . . , . - .
	, : ; ; ; ; ; .
	( - ). , . «» .

	, ( )
	/ ( PSP IBM): ( , ); ; ( , ); ( , , ); ( , -, ); ( , ); ( ); ( , , , , ); ( , ); , .
— , .
	: ; ; ; ; ; ; ; ; ; ; ; — , ; (e-mail).


	/ ( JIRA , [ ].[ ].[() ])

*	If the reason for transferring the requirement to the status “closed” is described, then this field shall indicate the details of the document confirming either the official recognition by the Customer that the requirement has been fulfilled or that the requirement has been canceled.
Decision
Software version	Software version number in which the requirement is implemented

* Features filling attribute, common to all types of tasks.

Changing the specific attributes of a task of the type “requirement” when transitioning from state to state is described by the following table, where:

- an attribute change is possible;

- required data entry.

To be continued

Many project managers believe that if the terms of reference were approved by the customer, then this is the ultimate truth, which is not subject to any changes. This is partly true - the wording of the requirements of the technical specifications is unlikely to be changed until the project is completed. However, already at the initial stages of the project (long before the approval of the Program and test procedure), no one bothers to clarify with the customer the boundaries of each requirement and fix the proposed procedure for its verification. If such work has not been carried out, then most likely all of the “Wishlist” of the customer expressed during the implementation, you will decide within the budget and the timing of the same project.

Do not forget about the objective laws, which drew the attention of Barry Boehm ( Barry W. Boehm ) back in the late 80s of the last century. If the project manager does not care about eliminating the uncertainty and inaccuracies of the requirements at the initial stages of the project, then by the phase of completion of the project he is guaranteed to have many unpleasant “discoveries”.

However, experience has shown that most of the ambiguities cannot be resolved by simply clarifying the requirements. In addition, it is often impossible to consider requirements in isolation from each other, since the goals in the interests of which the software is created can be achieved only with the integrated implementation of the customer's wishes.

Within the framework of the described approach, the coordination of an interconnected set of requirements, as well as a realistic interpretation of customer fantasies reflected in the approved terms of reference, is proposed to be carried out when solving problems of the “analysis” type, the features of which will be presented in the article “JIRA: rules for the timely preparation of tasty software. TLDR 3: Design Solutions. ”

JIRA: rules for the timely preparation of delicious software. TLDR 2: requirements management

Rules for slicing requirements

Rules for coloring cockroaches

Requirement Freezing Rules

To be continued

More articles: