Documenting Requirements: Small Mistakes That Cause Bigger Problems
The article is intended for business and system analysts who form requirements for information systems. Also, this information will be useful to developers and other persons working in the business of software production. The article discusses the formation and documentation of requirements. In particular, it considers the case when the analyst is told: “all your requirements are useless, because they don’t explain to the developer what to do and, most importantly, why . ”
Let us analyze the process as it usually happens. The analyst receives a request to change the functionality in the form of a ticket from technical support, technical specifications or direct customer complaints. The essence of the request is that something in the system is bad and you need to think about how to fix it. Or what needs to be done here on this screen is another such opportunity. Or it is necessary that “the user has the opportunity to do this . ” Often, the analyst simply writes down the request as it came: in the form of several sentences or a user story, forms from this a change task (or several tasks) and sends it to the developer. Then what happens is described in the last sentence of the previous paragraph. We will understand why.
Problem number 1 . What is incomprehensible to the developer? It is not clear to him which screens in the system to change, which buttons, fields, tabs and APIs, etc., need to be improved / created in order to fulfill customer requirements. What comes from the analyst is functional requirements , and the developer needs a functional specification (other names: implementation, design) with a detailed description of the necessary changes. For example, instead of describing the functionality with level detail
')
“When the user clicks the OK button, the dialog window closes and the main window that was before the dialogue appears is in focus.” (functional specification)
developer gets a description with level details
“The user should be able to close the dialog box and return to the main window” (functional requirement).
The last description is missing 2 implementation details:
* the window closes when you click OK,
* Focus returns to the main window automatically.
Even if the developer independently finishes these missing details, their absence in the text of the original task will create problems. For example, the tester will not understand what to check in this task. As a rule, in such cases, testers go / call developers and ask to tell "what exactly was done" as part of this task. To determine the exact behavior of this functionality in the future, for example, when a defect (bug) appears or when changes are necessary, developers will need to examine the source code of the revision “ where exactly everything worked correctly ”, and from testers to find the corresponding test case. All this entails additional time costs compared to simply reading the functional specification, which could be fixed in the original task by the analyst.
Many analysts deliberately do not describe the functional specification and are limited to only the requirements, because they want to leave the freedom to choose a solution to the developer. And many developers even require (!) That the task has no implementation details and that they have the freedom to choose exactly how to implement the functional requirement. There are two reasons for this: 1) the developer’s desire to know why change anything at all; 2) the existence of several ways to implement the same functional requirement in the system, of which (by sheer bad luck) the analyst chose not the simplest. There is also a third reason, the developer's own ego, but in this article we will not discuss it. The first reason, “the desire to know why” is discussed below. What to do with the second is recommended to discuss with the developer the main points of the functional specifications. And, whenever possible, to do it __ fixing of the specification in the text to a task. If there is no opportunity to discuss (for example, if developers are located in 10 time zones from you or at a contracting company), you still need to write down the specification in the task, and then send it to the developer for approval. The effectiveness of this approach will be higher, since the analyst’s time spent on the subsequent rewriting of the task will still be less than the time spent by several people on finding out the exact system behavior caused by the absence of a specification in the task.
Often the question arises whether the analyst should describe the database requirements in the task, for example, the structure of tables, field names, and so on. The short answer is no. The analyst must specify only the part of the software that is visible to the user. These are user interface, public API and visible hardware parameters, for example, monitor size. Yes, in this article we are talking about software, but since in a “pure” form, almost no one uses it and the user always interacts with the program through the equipment layer, the specification of requirements must specify the permissible parameters of this layer.
Another common mistake of both analysts and developers is the description of the implementation details (in fact, the functional specification) in the _commenting_ to the task. And often several comments are created for the same functionality (this is called a discussion). Whether because of this should not use the comments? Of course not, but the intermediate agreements on the functional specification, and especially the final ones, should be recorded precisely in the text of the task, and not elsewhere. And again, we mention that the best way to agree is to call the developer and discuss the main details with a voice, and only then record them in the task.
Problem number 2. Why the developer does not understand "why to do" ? Because the task lacks what is called a business requirement (other names: problem or problem statement ), or, more often, from the description of the business requirement, the original problem of the user is still not clear, because the software itself is mentioned too much in the description , not a business or user situation. One example of an incomprehensible description of the problem:
“In the system directories the field“ name English ”is implemented, but the field has never been filled. The presence of blank fields in the directories does not suit the customer, because points to the irrelevance of directories . "
Well, irrelevant reference books, so what? Who suffers from this? By collecting quite a bit of additional information, you can describe the problem better:
“Client administrators spend extra time monitoring the relevance of classifiers presented in the form of reference books. This is due to the presence in the list of directory elements of additional fields, about which it is not clear to fill them out or not. ”
What has changed? First, the specific people who have the problem (administrators) have become obvious. Secondly, the measurement of the problem has become clear (time consuming). If you still understand how often classifiers are controlled (wasted time), you can already determine the priority of the problem (and the tasks). And if you still explain why classifiers should be relevant at all, then you get a completely perfect description.
The description of the problem is also called the “problem statement” (see link above) and, although Goldsmith already lists six steps to determine it, it makes sense to simplify to just 3x:
Step 1. User category description;
Step2. Definition and description of the user's business problem, which is either not solved, or requires additional time / money, or is punishable for violating the law;
Step3. Description of the lack of software that does not allow to solve a business problem.
It is recommended that the order of describing the problem, because no one wants to read extra words - a description of the software.
In conclusion, summarizing these problems, I would like to note that the analyst should spend time and not on what when documenting the requirements. Only two things are crucial: documenting the user's problem and documenting the functional specification of changes. These two points should be present in each task for developers and testers. This is guaranteed to solve the problem voiced at the beginning of the article.
For all other requirements management and documentation activities, such as functional and non-functional requirements, user stories, use cases, time needs to be minimized, because none of this explains the most important things: 1) what exactly to develop / test, 2) who users will benefit from these actions and what is his problem now. Functional requirements are needed when it is impossible to cover a functional specification due to the scope of the problem description (by business requirements). As a result, an intermediate, more compact, layer of requirements is created, which ultimately still leads to the appearance of a specification. But since this layer of requirements is intermediate, it is advisable to skip it - which saves time.
PS Template for describing the task in JIRA. Tasks (but not bugs) are drawn up according to the following patterns for the Summary , Problem , Description fields. All 3 fields are required.
Summary :
Problem :
Description :
Let us analyze the process as it usually happens. The analyst receives a request to change the functionality in the form of a ticket from technical support, technical specifications or direct customer complaints. The essence of the request is that something in the system is bad and you need to think about how to fix it. Or what needs to be done here on this screen is another such opportunity. Or it is necessary that “the user has the opportunity to do this . ” Often, the analyst simply writes down the request as it came: in the form of several sentences or a user story, forms from this a change task (or several tasks) and sends it to the developer. Then what happens is described in the last sentence of the previous paragraph. We will understand why.
Problem number 1 . What is incomprehensible to the developer? It is not clear to him which screens in the system to change, which buttons, fields, tabs and APIs, etc., need to be improved / created in order to fulfill customer requirements. What comes from the analyst is functional requirements , and the developer needs a functional specification (other names: implementation, design) with a detailed description of the necessary changes. For example, instead of describing the functionality with level detail
')
“When the user clicks the OK button, the dialog window closes and the main window that was before the dialogue appears is in focus.” (functional specification)
developer gets a description with level details
“The user should be able to close the dialog box and return to the main window” (functional requirement).
The last description is missing 2 implementation details:
* the window closes when you click OK,
* Focus returns to the main window automatically.
Even if the developer independently finishes these missing details, their absence in the text of the original task will create problems. For example, the tester will not understand what to check in this task. As a rule, in such cases, testers go / call developers and ask to tell "what exactly was done" as part of this task. To determine the exact behavior of this functionality in the future, for example, when a defect (bug) appears or when changes are necessary, developers will need to examine the source code of the revision “ where exactly everything worked correctly ”, and from testers to find the corresponding test case. All this entails additional time costs compared to simply reading the functional specification, which could be fixed in the original task by the analyst.
Many analysts deliberately do not describe the functional specification and are limited to only the requirements, because they want to leave the freedom to choose a solution to the developer. And many developers even require (!) That the task has no implementation details and that they have the freedom to choose exactly how to implement the functional requirement. There are two reasons for this: 1) the developer’s desire to know why change anything at all; 2) the existence of several ways to implement the same functional requirement in the system, of which (by sheer bad luck) the analyst chose not the simplest. There is also a third reason, the developer's own ego, but in this article we will not discuss it. The first reason, “the desire to know why” is discussed below. What to do with the second is recommended to discuss with the developer the main points of the functional specifications. And, whenever possible, to do it __ fixing of the specification in the text to a task. If there is no opportunity to discuss (for example, if developers are located in 10 time zones from you or at a contracting company), you still need to write down the specification in the task, and then send it to the developer for approval. The effectiveness of this approach will be higher, since the analyst’s time spent on the subsequent rewriting of the task will still be less than the time spent by several people on finding out the exact system behavior caused by the absence of a specification in the task.
Often the question arises whether the analyst should describe the database requirements in the task, for example, the structure of tables, field names, and so on. The short answer is no. The analyst must specify only the part of the software that is visible to the user. These are user interface, public API and visible hardware parameters, for example, monitor size. Yes, in this article we are talking about software, but since in a “pure” form, almost no one uses it and the user always interacts with the program through the equipment layer, the specification of requirements must specify the permissible parameters of this layer.
Another common mistake of both analysts and developers is the description of the implementation details (in fact, the functional specification) in the _commenting_ to the task. And often several comments are created for the same functionality (this is called a discussion). Whether because of this should not use the comments? Of course not, but the intermediate agreements on the functional specification, and especially the final ones, should be recorded precisely in the text of the task, and not elsewhere. And again, we mention that the best way to agree is to call the developer and discuss the main details with a voice, and only then record them in the task.
Problem number 2. Why the developer does not understand "why to do" ? Because the task lacks what is called a business requirement (other names: problem or problem statement ), or, more often, from the description of the business requirement, the original problem of the user is still not clear, because the software itself is mentioned too much in the description , not a business or user situation. One example of an incomprehensible description of the problem:
“In the system directories the field“ name English ”is implemented, but the field has never been filled. The presence of blank fields in the directories does not suit the customer, because points to the irrelevance of directories . "
Well, irrelevant reference books, so what? Who suffers from this? By collecting quite a bit of additional information, you can describe the problem better:
“Client administrators spend extra time monitoring the relevance of classifiers presented in the form of reference books. This is due to the presence in the list of directory elements of additional fields, about which it is not clear to fill them out or not. ”
What has changed? First, the specific people who have the problem (administrators) have become obvious. Secondly, the measurement of the problem has become clear (time consuming). If you still understand how often classifiers are controlled (wasted time), you can already determine the priority of the problem (and the tasks). And if you still explain why classifiers should be relevant at all, then you get a completely perfect description.
The description of the problem is also called the “problem statement” (see link above) and, although Goldsmith already lists six steps to determine it, it makes sense to simplify to just 3x:
Step 1. User category description;
Step2. Definition and description of the user's business problem, which is either not solved, or requires additional time / money, or is punishable for violating the law;
Step3. Description of the lack of software that does not allow to solve a business problem.
It is recommended that the order of describing the problem, because no one wants to read extra words - a description of the software.
In conclusion, summarizing these problems, I would like to note that the analyst should spend time and not on what when documenting the requirements. Only two things are crucial: documenting the user's problem and documenting the functional specification of changes. These two points should be present in each task for developers and testers. This is guaranteed to solve the problem voiced at the beginning of the article.
For all other requirements management and documentation activities, such as functional and non-functional requirements, user stories, use cases, time needs to be minimized, because none of this explains the most important things: 1) what exactly to develop / test, 2) who users will benefit from these actions and what is his problem now. Functional requirements are needed when it is impossible to cover a functional specification due to the scope of the problem description (by business requirements). As a result, an intermediate, more compact, layer of requirements is created, which ultimately still leads to the appearance of a specification. But since this layer of requirements is intermediate, it is advisable to skip it - which saves time.
PS Template for describing the task in JIRA. Tasks (but not bugs) are drawn up according to the following patterns for the Summary , Problem , Description fields. All 3 fields are required.
Summary :
<Task name. Instead of the general words “refinement”, “change”, “task to”, it is recommended to indicate a specific action performed in a task or the most important of several actions>
Problem :
<Problem description: user (s), impossibility / complexity of implementing a business task / process by means of software or discrepancy between a business task and software>.
Description :
<optional> Where : <Exact description of the procedure for the user to access the software screen on which changes are to be made>.
<Exact description of all changes in software visible to the user. Without mentioning the details of the business process and the reasons why changes are required>
<optional> Task for implementation :
<An exact description of all configuration settings in the software, including invisible to the user, which must be carried out after the release of changes. For example, running a script or setting up directories>
Source: https://habr.com/ru/post/299930/
All Articles