Some remarks on gathering requirements for software development.
Recently, my friend complained about the dominance of English slang in some professional communities. I answered him that it was bad, but forced. It is just like this that the natural process of borrowing takes place, where the necessary adapts, and the unnecessary is swept aside. And in the English language there are much more Latinisms than in Russian Anglicisms. After all, once those who were engaged in science, spoke exclusively in Latin.
In the Russian language there is a small area where it is required to bring it to modern realities. This applies to Western practices in the management of people and groups. They were poorly studied by Soviet science, while in the 90s they began their accelerated introduction by people who quite recently considered them ideologically incorrect. So it was with economics and in more specific areas, for example, concerning the production of software.
We have always been able to write excellent program code. But the software business is broader than simple hired programming — it’s a knowledge trade. And if so, it requires production and its organization. Here, the key role is played by requirements collection management systems, where the production process has to be built on the basis of western experience.
Later in the article, typical borrowing errors are analyzed using examples from the translation of the “Software Requirements Development” book by Karl I. Wigs. At the end, the material under discussion is summarized using the V-model of the life cycle of the software design requirements.
Certainly the curious book by Karl I. Wigers “Developing Software Requirements” (hereinafter RTKPO) is becoming a kind of standard in the Russian information community. But the use of the provisions from this book (borrowed, original, translated) outside the author's concept raises questions that I would like to understand.
This is an illustration of the development of requirements as the project progresses from top to bottom, through three documents: “ Document about the image and boundaries of the project ”, “ Document about use cases ”, and “ Specification of software requirements ”. In the 3rd edition, the two first documents are presented as “ Concept and Boundary Document ” and “ User Requirements Document ”
To create the right document, you must first understand its essence. It seems that it is a matter of unraveling the mysterious “ image and boundaries of the project ”: I guessed it — and you can use the already existing practice without limitations and with great benefit. Unfortunately, this only works with simple technologies purchased from third parties. Aspects of team management are directly related to the characteristics of a foreign culture, and there everything is far from simple. Cultural differences are the visible part of the iceberg of the entire system of subconscious ethnic behavioral stereotypes. And we do not control the area of the unconscious at all, or only partially control it.
However, not everything is so hopeless. It is necessary to find associations of their terminology with our practice. Let us examine the " Document about the image and boundaries of the project ." The boundaries of the project - the project scope . This should be translated as “ scope of work ”. Not in the dictionary? Alas. You can look at the English directory: project scope - part of the project planning, which includes the process of determining and then documenting specific project goals, results, objectives, costs and deadlines . There is a specific procedure, why not call it “the boundaries of the project ”? In this case, there will be problems with the integration of our own past experience: after all, we have been engaged in planning and, in particular, in determining the scope of work.
When a dictionary translation fails, you need to look for a simple conceptual model illustrating the use of a controversial term in a close subject area. Further transfer of such a simple model of disclosure to the native soil allows us to find language correspondences. The model “Triangle constraints” (triple constrains) is an introduction to project management.
This model reveals the connection between the terms " execution time ", " cost ", " scope of work " (time, cost, scope), which are placed in the form of an equilateral triangle, implying that changing one side of this triangle leads to a change in all.
Project Vision is sometimes translated not as a “ project image ”, but as a “ project concept ”, but this does not add clarity. The Project Vision Statement in the directory is defined as “an idealistic view of the desired business results that will be obtained upon successful completion of the project ”. We usually use the term “ project objectives ” and formulate these tasks with a share of domestic pessimism. If we call it the “ image of the project ”, it is unlikely that this will help to manifest Western optimism on one’s own soil. Total, the first document can be called " The objectives of the project and scope of work ." And nothing mysterious.
There is an opinion that such terms need not be translated, but used in the project English. This works only partly, severely limiting the circle of people who understand matters at the expert level. Basic language skills are not enough where technological issues concern ethno-cultural differences.
Here is a typical example from the RTKPO: “ Requirements should be stated sequentially, for example,“ the system will be ... ”or“ the user will be ... ”, then the active verb, and then the observed result ... You can use“ must ”as a synonym for“ will ”, but avoid “should”, “can”, “could” and similar words, from which it is not clear whether action is necessary . ”
You might think that this is a ready-made guide to action. In fact, this translation does not help to understand, but still confuses more. Moreover, the English original is not the ultimate truth, but an expression of a certain view of the modality of the English language. The view is enshrined in the RFC2119 standard **, which specifies the rules for the use of English keywords in requirements management ( eg must, shall, should, may ). For example, by this standard, must means " that the definition is an absolute specification requirement. " However, the author met document templates with a direct prohibition of the use of must (an explanation of this position is available on the Internet ***).
The next level of detail of requirements is the “ Document on Use Options ”. In the RTKPO, it is indicated that it defines use cases, scenarios, and event-response tables. Translation of the “ use cases ” as “ use cases ” unnecessarily simplifies the view of things (because in practice Anglicism has become entrenched with the use of key cases). Modern software should have protection against hacking and protection against a fool, but consider it a use case - violence over the Russian language. For the translation proposed "interaction scenarios."
In fact, the “ event-response ” model is known to us. In high school, it is studied as " impact - fluctuation -> response ." With the same impacts, the response of the system may vary due to random fluctuations. In user software, these are usually various error situations. Additionally, at the concept level, the effects of the environment should be distinguished from those of the user. A more or less suitable name for this level of requirements is “ System Requirements ” or already “ Requirements for a software product ”, although the terminology is not settled, and there are very different options (for example, in the latest edition the name “ User Requirements Document ” is used that automatically excludes embedded systems from consideration).
The essence of the development of requirements at this level is the creation of a detailed speculative software model that functions in an idealized external world. Therefore, an important point is the assignment of constraints and the assumptions. “The color of the car can be any under the condition that it is black ,” so Henry Ford re-worked the business requirement for the color of the car into an assumption. However, another time to meet the business requirements for the cleanliness of the car turned out to be necessary to make a non-planar streamlined glass. Ford engineers said it was technically impossible. Ford found young inventors on the side.
The lower level is represented by the “ Software Requirements Specification ”, which includes “ restrictions ”, “ external interface ”, “ quality attributes ” and “ functional requirements ” itself. This is the last document in the figure, unfortunately, the questions of subsequent testing are not affected. Therefore, to formulate the definition of a RTKPO, it is necessary to involve the concept of business requirements: " functional requirements (functional requirements) define the software functionality that developers must build so that users can complete their tasks within the business requirements "
From the testing side, the definition is simpler to build: “ Functional requirements are requirements that are being tested .” This should be understood as the ability to test each functional requirement with a test in the classical sense (with a verdict - passed or failed). The converse, strictly speaking, is wrong: some tests may exist by themselves. But the presence of such tests - an indicator of gaps in the work on the requirements. After all, the test checks any part of the code that did not appear by itself, but as a result of the execution of a certain functional requirement.
Modern mature software development processes are trying to make the measurement component already in the early stages of the software product manufacturing. Without going into details - for the most part these are all kinds of coverage metrics. One of the indicators of the quality of a future product is the percentage of test coverage of functional requirements, which is calculated using the traceability matrix. It is possible to include a non-functional requirement in the matrix, but in future work it will be marked as untestable, and, most importantly, testers will evaluate it as useless. It seems that a complete “ specification of software requirements ” with a list of non-functional requirements is very useful for programmers. And this might have been the case if, after drawing up, they would drop in there, at least from time to time.
The vast majority of non-functional requirements can be written in a functional way. To paraphrase, almost any non-functional requirement for a system or software product can be processed into one or several functional requirements.
The quality attributes in the RTKPO partially fall into the functional requirements, which is absolutely true. However, the limitations and external interface of the RTKPO defines: “ other non-functional requirements describe external interactions between the system and the outside world, design and implementation constraints. The constraints (constraints) relate to the choice of the possibility of developing the appearance and structure of the product . " Communication subsystems with the outside world always have an interface that is functional and subject to testing.
Can limitations be functional requirements? Definitely yes, if you write them in inverted form as possibilities. For example, the product must be faster than its competitors (otherwise it is not needed - a very strict limitation). First of all, we are talking about the novelty of the decisions made, documented, including in the form of requirements. But it is clear that the system should have a module for measuring the identified parameters of this speed, and at an early stage.
So, “ Functional specifications ” is the well-established name of the lower level specifications in the form of a formatted document or in the form of a database managed by specialized software.
What happens to the requirements next? In addition to developers (programmers), test engineers and QA (Quality Assurance) engineers will work with requirements. "Testing" can be translated as "testing", but borrowing "testing" apparently took place. The translation of QA again requires a model of disclosure - here, what principles underlie it. First, " Fit for purpose " (the product must be suitable for the intended purpose), secondly, " right first time " ("the first time" - the errors should be eliminated) and thirdly, project independence. This is " Acceptance ", the principles underlie the well-known military acceptance and the legendary state acceptance.
Requirement specifications will form the basis of further design documents. At a minimum, the requirements will be used in the development of user documentation . It is generally accepted that testing begins with a testing plan and ends with a testing report — documents directly related to specifications. It is possible to look at the figure in the RTKPO differently - as a generalized model of the software development process (or a model of the software life cycle). In this model, the finished documents are the entry / exit points between the phases of the process.
In chronological order, the documents will be presented as follows: business requirements (as part of the project scope), system requirements (PO), functional requirements, a test plan, a test report, user documentation. The line between the two documents - the process phase. Models are often drawn in the form of repeating cycles or spirals, but the simple chronological axis is more visual. Then the first and the last phase of the process are indicated not by a segment, but by a ray. In modern presentations, the time axis is bent in the middle of the coding phase in the form of the letter “ V ”, receiving the so-called V-model .
Broken lines show connections around the chronological axis, showing the opportunity to start some work in advance. For example, with the formulated business requirements, you can already say something about the user documentation of the product, and the generated requirements for the system will give a model of the future software, the quality of which you can already begin to evaluate.
But the main function of these lines is to show the possibility of scalability (simplification) of the V-model. Support for all phases and documents is always an expensive pleasure, and a very common reason for losing to more mobile competitors . For example, an individual works like this: business requirements -> development (coding) -> user documentation. This is the top dashed cut line. Outsourcing companies, as a rule, skip the lower phases, not spending on functional specifications and limited to one or another kind of system requirements (for example, interaction scenarios ). For products of the same type, there is usually an enterprise standard, and from the coding phase some kind of internal developer testing report is issued to start the “QA / Acceptance” phase.
Fundamental V-model helps clarify areas of responsibility. For example, an employee plays the role of an Acceptance Engineer (QA) or Testing Engineer, depending on which phase he is working. It does not matter whether it is assigned to a specific project or department. The same applies to the analyst, the designer, the developer - the ability to perform all these roles by one person does not disprove the V-model. For the Acceptance Engineer (QA) and the analyst, the basis is “System Requirements”, they work with the software being developed as a black box. For those involved in the design, development and testing phases, this is a white box, albeit in varying degrees.
In conclusion, it is worth noting that the V-model is still a presentation one (in this case, illustrating the design evolution of requirements). This is not a direct guide to action, the actual software development processes more difficult. But its revealing potential is difficult to diminish.
* Karl I. Wigers “Developing Software Requirements”.
** Key words for use in RFCs to Indicate Requirement Level (https://tools.ietf.org/html/rfc2119)
*** Must - don't need it. Also, it must be held in court, must has not. Granted, must does sounds stronger, right? I mean, if you’re going to do something, you’re going to do it. But, when writing requirements, keep things simple and just use shall (http://www.reqexperts.com/blog/2012/10/using-the-correct-terms-shall-will-should)
In the Russian language there is a small area where it is required to bring it to modern realities. This applies to Western practices in the management of people and groups. They were poorly studied by Soviet science, while in the 90s they began their accelerated introduction by people who quite recently considered them ideologically incorrect. So it was with economics and in more specific areas, for example, concerning the production of software.
We have always been able to write excellent program code. But the software business is broader than simple hired programming — it’s a knowledge trade. And if so, it requires production and its organization. Here, the key role is played by requirements collection management systems, where the production process has to be built on the basis of western experience.
Later in the article, typical borrowing errors are analyzed using examples from the translation of the “Software Requirements Development” book by Karl I. Wigs. At the end, the material under discussion is summarized using the V-model of the life cycle of the software design requirements.
Certainly the curious book by Karl I. Wigers “Developing Software Requirements” (hereinafter RTKPO) is becoming a kind of standard in the Russian information community. But the use of the provisions from this book (borrowed, original, translated) outside the author's concept raises questions that I would like to understand.
This is an illustration of the development of requirements as the project progresses from top to bottom, through three documents: “ Document about the image and boundaries of the project ”, “ Document about use cases ”, and “ Specification of software requirements ”. In the 3rd edition, the two first documents are presented as “ Concept and Boundary Document ” and “ User Requirements Document ”
To create the right document, you must first understand its essence. It seems that it is a matter of unraveling the mysterious “ image and boundaries of the project ”: I guessed it — and you can use the already existing practice without limitations and with great benefit. Unfortunately, this only works with simple technologies purchased from third parties. Aspects of team management are directly related to the characteristics of a foreign culture, and there everything is far from simple. Cultural differences are the visible part of the iceberg of the entire system of subconscious ethnic behavioral stereotypes. And we do not control the area of the unconscious at all, or only partially control it.
However, not everything is so hopeless. It is necessary to find associations of their terminology with our practice. Let us examine the " Document about the image and boundaries of the project ." The boundaries of the project - the project scope . This should be translated as “ scope of work ”. Not in the dictionary? Alas. You can look at the English directory: project scope - part of the project planning, which includes the process of determining and then documenting specific project goals, results, objectives, costs and deadlines . There is a specific procedure, why not call it “the boundaries of the project ”? In this case, there will be problems with the integration of our own past experience: after all, we have been engaged in planning and, in particular, in determining the scope of work.
When a dictionary translation fails, you need to look for a simple conceptual model illustrating the use of a controversial term in a close subject area. Further transfer of such a simple model of disclosure to the native soil allows us to find language correspondences. The model “Triangle constraints” (triple constrains) is an introduction to project management.
This model reveals the connection between the terms " execution time ", " cost ", " scope of work " (time, cost, scope), which are placed in the form of an equilateral triangle, implying that changing one side of this triangle leads to a change in all.
Project Vision is sometimes translated not as a “ project image ”, but as a “ project concept ”, but this does not add clarity. The Project Vision Statement in the directory is defined as “an idealistic view of the desired business results that will be obtained upon successful completion of the project ”. We usually use the term “ project objectives ” and formulate these tasks with a share of domestic pessimism. If we call it the “ image of the project ”, it is unlikely that this will help to manifest Western optimism on one’s own soil. Total, the first document can be called " The objectives of the project and scope of work ." And nothing mysterious.
There is an opinion that such terms need not be translated, but used in the project English. This works only partly, severely limiting the circle of people who understand matters at the expert level. Basic language skills are not enough where technological issues concern ethno-cultural differences.
Here is a typical example from the RTKPO: “ Requirements should be stated sequentially, for example,“ the system will be ... ”or“ the user will be ... ”, then the active verb, and then the observed result ... You can use“ must ”as a synonym for“ will ”, but avoid “should”, “can”, “could” and similar words, from which it is not clear whether action is necessary . ”
You might think that this is a ready-made guide to action. In fact, this translation does not help to understand, but still confuses more. Moreover, the English original is not the ultimate truth, but an expression of a certain view of the modality of the English language. The view is enshrined in the RFC2119 standard **, which specifies the rules for the use of English keywords in requirements management ( eg must, shall, should, may ). For example, by this standard, must means " that the definition is an absolute specification requirement. " However, the author met document templates with a direct prohibition of the use of must (an explanation of this position is available on the Internet ***).
The next level of detail of requirements is the “ Document on Use Options ”. In the RTKPO, it is indicated that it defines use cases, scenarios, and event-response tables. Translation of the “ use cases ” as “ use cases ” unnecessarily simplifies the view of things (because in practice Anglicism has become entrenched with the use of key cases). Modern software should have protection against hacking and protection against a fool, but consider it a use case - violence over the Russian language. For the translation proposed "interaction scenarios."
In fact, the “ event-response ” model is known to us. In high school, it is studied as " impact - fluctuation -> response ." With the same impacts, the response of the system may vary due to random fluctuations. In user software, these are usually various error situations. Additionally, at the concept level, the effects of the environment should be distinguished from those of the user. A more or less suitable name for this level of requirements is “ System Requirements ” or already “ Requirements for a software product ”, although the terminology is not settled, and there are very different options (for example, in the latest edition the name “ User Requirements Document ” is used that automatically excludes embedded systems from consideration).
The essence of the development of requirements at this level is the creation of a detailed speculative software model that functions in an idealized external world. Therefore, an important point is the assignment of constraints and the assumptions. “The color of the car can be any under the condition that it is black ,” so Henry Ford re-worked the business requirement for the color of the car into an assumption. However, another time to meet the business requirements for the cleanliness of the car turned out to be necessary to make a non-planar streamlined glass. Ford engineers said it was technically impossible. Ford found young inventors on the side.
The lower level is represented by the “ Software Requirements Specification ”, which includes “ restrictions ”, “ external interface ”, “ quality attributes ” and “ functional requirements ” itself. This is the last document in the figure, unfortunately, the questions of subsequent testing are not affected. Therefore, to formulate the definition of a RTKPO, it is necessary to involve the concept of business requirements: " functional requirements (functional requirements) define the software functionality that developers must build so that users can complete their tasks within the business requirements "
From the testing side, the definition is simpler to build: “ Functional requirements are requirements that are being tested .” This should be understood as the ability to test each functional requirement with a test in the classical sense (with a verdict - passed or failed). The converse, strictly speaking, is wrong: some tests may exist by themselves. But the presence of such tests - an indicator of gaps in the work on the requirements. After all, the test checks any part of the code that did not appear by itself, but as a result of the execution of a certain functional requirement.
Modern mature software development processes are trying to make the measurement component already in the early stages of the software product manufacturing. Without going into details - for the most part these are all kinds of coverage metrics. One of the indicators of the quality of a future product is the percentage of test coverage of functional requirements, which is calculated using the traceability matrix. It is possible to include a non-functional requirement in the matrix, but in future work it will be marked as untestable, and, most importantly, testers will evaluate it as useless. It seems that a complete “ specification of software requirements ” with a list of non-functional requirements is very useful for programmers. And this might have been the case if, after drawing up, they would drop in there, at least from time to time.
The vast majority of non-functional requirements can be written in a functional way. To paraphrase, almost any non-functional requirement for a system or software product can be processed into one or several functional requirements.
The quality attributes in the RTKPO partially fall into the functional requirements, which is absolutely true. However, the limitations and external interface of the RTKPO defines: “ other non-functional requirements describe external interactions between the system and the outside world, design and implementation constraints. The constraints (constraints) relate to the choice of the possibility of developing the appearance and structure of the product . " Communication subsystems with the outside world always have an interface that is functional and subject to testing.
Can limitations be functional requirements? Definitely yes, if you write them in inverted form as possibilities. For example, the product must be faster than its competitors (otherwise it is not needed - a very strict limitation). First of all, we are talking about the novelty of the decisions made, documented, including in the form of requirements. But it is clear that the system should have a module for measuring the identified parameters of this speed, and at an early stage.
So, “ Functional specifications ” is the well-established name of the lower level specifications in the form of a formatted document or in the form of a database managed by specialized software.
What happens to the requirements next? In addition to developers (programmers), test engineers and QA (Quality Assurance) engineers will work with requirements. "Testing" can be translated as "testing", but borrowing "testing" apparently took place. The translation of QA again requires a model of disclosure - here, what principles underlie it. First, " Fit for purpose " (the product must be suitable for the intended purpose), secondly, " right first time " ("the first time" - the errors should be eliminated) and thirdly, project independence. This is " Acceptance ", the principles underlie the well-known military acceptance and the legendary state acceptance.
Requirement specifications will form the basis of further design documents. At a minimum, the requirements will be used in the development of user documentation . It is generally accepted that testing begins with a testing plan and ends with a testing report — documents directly related to specifications. It is possible to look at the figure in the RTKPO differently - as a generalized model of the software development process (or a model of the software life cycle). In this model, the finished documents are the entry / exit points between the phases of the process.
In chronological order, the documents will be presented as follows: business requirements (as part of the project scope), system requirements (PO), functional requirements, a test plan, a test report, user documentation. The line between the two documents - the process phase. Models are often drawn in the form of repeating cycles or spirals, but the simple chronological axis is more visual. Then the first and the last phase of the process are indicated not by a segment, but by a ray. In modern presentations, the time axis is bent in the middle of the coding phase in the form of the letter “ V ”, receiving the so-called V-model .
Broken lines show connections around the chronological axis, showing the opportunity to start some work in advance. For example, with the formulated business requirements, you can already say something about the user documentation of the product, and the generated requirements for the system will give a model of the future software, the quality of which you can already begin to evaluate.
But the main function of these lines is to show the possibility of scalability (simplification) of the V-model. Support for all phases and documents is always an expensive pleasure, and a very common reason for losing to more mobile competitors . For example, an individual works like this: business requirements -> development (coding) -> user documentation. This is the top dashed cut line. Outsourcing companies, as a rule, skip the lower phases, not spending on functional specifications and limited to one or another kind of system requirements (for example, interaction scenarios ). For products of the same type, there is usually an enterprise standard, and from the coding phase some kind of internal developer testing report is issued to start the “QA / Acceptance” phase.
Fundamental V-model helps clarify areas of responsibility. For example, an employee plays the role of an Acceptance Engineer (QA) or Testing Engineer, depending on which phase he is working. It does not matter whether it is assigned to a specific project or department. The same applies to the analyst, the designer, the developer - the ability to perform all these roles by one person does not disprove the V-model. For the Acceptance Engineer (QA) and the analyst, the basis is “System Requirements”, they work with the software being developed as a black box. For those involved in the design, development and testing phases, this is a white box, albeit in varying degrees.
In conclusion, it is worth noting that the V-model is still a presentation one (in this case, illustrating the design evolution of requirements). This is not a direct guide to action, the actual software development processes more difficult. But its revealing potential is difficult to diminish.
* Karl I. Wigers “Developing Software Requirements”.
** Key words for use in RFCs to Indicate Requirement Level (https://tools.ietf.org/html/rfc2119)
*** Must - don't need it. Also, it must be held in court, must has not. Granted, must does sounds stronger, right? I mean, if you’re going to do something, you’re going to do it. But, when writing requirements, keep things simple and just use shall (http://www.reqexperts.com/blog/2012/10/using-the-correct-terms-shall-will-should)
All Articles