Modern methods for describing functional requirements for systems. Alistair Coburn. Book review and additions
The book describes one method of writing part of the statement of the problem, namely the use case method.
What it is? This is a description of the scenario of user interaction with the system (or business). The system at the same time acts as a black box (and this makes it possible to divide the complex design task into designing the interaction and ensuring this interaction). At the same time, notation standards are introduced, which ensures ease of reading, including for non-participants, and allows you to make some checks for completeness and compliance with the goals of the stakeholder.
What the scenario looks like, using the example of authorization on the site via email:
(System) Log in to the site to access your personal account. ~~ (sea level)
Context: An unauthorized client is authorized on the site so that the site recognizes it and displays personal information for it: browsing history, purchases, the current number of bonus points, etc., using email as a login.
Level: User Goal
Main actor: customer (visitor to our online store)
Scope: Customer interaction with the website of the online store
Interested parties and interests:
Preconditions: the visitor must not be logged in.
Minimum guarantees: the visitor finds out the fact of a successful or unsuccessful attempt to log in.
Guarantees of success: the visitor is authorized.
The main scenario:
Extensions:
2.a. Client is already authorized:
2.a.1. The system notifies the client of the fact of the authorization made earlier and suggests either aborting the script or proceeding to step 4, while if step 6 was successfully completed, then step 7 is carried out with the clarification:
2.a.7. The system deactivates the client under the old account, authorizes the client under the new account, while the browsing history and basket of this interaction session remains in the old account, does not go into the new one. Next, go to step 8.
2.b The number of authorization attempts exceeded the threshold under "Security Rule No. 23":
2.b.1 Go to step 4, the captcha is additionally displayed on the authorization form
2.b.6 The system confirms the correct entry of captcha
2.b.6.1 Captcha entered incorrectly:
2.b.6.1.1. the system increases the counter of unsuccessful authorization attempts for this account as well
2.b.6.1.2. the system displays a failure message and returns to step 2
6.a. No account was found with this email:
6.a.1. The system displays a message about the failure and offers a choice of either a transition to step 2 or a transition to the “User Registration” scenario with saving the entered email,
6.b. The password from the account with this email does not match the entered:
6.b.1 The system increases the counter of unsuccessful attempts to enter this account.
6.b.2 The system displays a failure message and offers to choose either a transition to the “Password recovery” scenario or a transition to step 2.
6.c: The counter of attempts to enter this account has exceeded the threshold under the "Security Rule No. 24".
6.v.1 The system displays a message about blocking the entrance to the account for X minutes and proceeds to step 2.
Checks for completeness and compliance with goals, that is, you can give the requirements for verification to another analyst, allowing fewer errors at the stage of setting the task.
Working with a system such as a black box allows you to share the development and coordination with the customer of what will be automated from the implementation methods.
It is part of the analyst’s path, one of the main parts of usability. The user’s script sets the main paths for his movement, which greatly reduces the freedom of choice for the designer and the customer and helps to increase the speed of design development.
It is very pleasing in the description of the place where the exceptions of each interaction step are revealed. A holistic IT system should provide for one or another exception handling, part in manual mode, part in automatic (as in the example above).
Experience has shown that poorly thought out exception handling can easily turn a system into a terribly inconvenient system. I recall a story when in Soviet times it took several approvals from different services to get a decision, and it hurts when the last service says - and you have a wrong name or some other mistake in punctuation, redo everything and reconcile everything.
Often I encounter situations where the system logic that was not thought out for exceptions required a significant alteration of this system. Because of this, the lion's share of the analyst’s work is spent on handling exceptions.
Text notation, unlike diagrams, allows you to identify and cover more exceptions.
Use case is not an independently prioritized part of the production, unlike a user story.
In this scenario, consider the exception “6.a. No account with this email was found. ”And the next step“ 6.a.1. The system displays a failure message and proceeds to step 2 ”. What of the negative remains behind the scenes? For the client, any return is equivalent to the fact that all the work that he has done entering the data is thrown into the landfill. (This is simply not visible in the script!) What can be done? Rebuild the script so that this does not occur. Can this be done? You can - as an example, look at the authorization script in Google.
The book talks about formalization, but talks little about optimization methods for such scenarios.
But it is possible to strengthen the method by optimizing scripts and the use case formalization method allows this. Specifically, for each exception that occurs, you need to think about it, determine the reason and rebuild the script so as to get rid of the exception or minimize the client’s path.
In ordering the online store you need to enter the city of delivery. It may turn out that for a city chosen by a customer, a store cannot deliver goods because it does not deliver there, due to overall restrictions or due to the lack of goods in the corresponding warehouse.
If you simply describe the interaction scenario at the design stage, you can write “inform the customer about the impossibility of delivery and offer to change the city or the composition of the basket” (and many novice analysts stop at this). But if there are a lot of such cases, then you can optimize the scenario.
The first thing to do is to give only the city where we can make the delivery. When to do it? Before the moment of choosing a product on the site (city auto-detection via ip with specification).
The second - you need to give a choice only of the goods that we can deliver to the client. When to do it? At the time of selection - on the goods tile and product card.
These two changes significantly eliminate this exception.
Considering the task of minimizing the handling of exceptions, you can put the task on reporting (use case is not described). How many exceptions were, in what cases they occurred, plus how many scenarios were successful from incoming ones.
But alas. Experience has shown that reporting requirements for scenarios in this form are not enough, you need to consider reporting requirements for processes that are described mainly not in the form of a use case.
In our practice, we have expanded the use case description form with the description of specific attributes of entities and data for decision-making by the client, which enhances the subsequent usability.
For usability design, we added an input section - the displayed data.
In an authorization scenario, this is a fact of client authorization in the system. If the client is pre-authorized, then display a warning about switching the navigation history and the basket to the new account after successful authorization.
In the general case, this is a mapping of the necessary information for the client so that he can make a decision about his further actions according to the scenario (one may ask if the client has enough of this data, what else is needed, what information is needed for the client to make decisions).
It is also worth splitting the input information into the input fields if they are processed separately and with the formation of various exceptions.
In the example with client authorization, if you select the entered information with a username and password, then you should change the authorization script with the separate steps for entering a separate login and password (and this is done in Yandex, Google, but not in most online stores).
The requirements for data transformation algorithms can also be pulled out of the script.
Examples:
In general, after reading the book, unfortunately, it is not clear how to go the entire way of the analyst from business problems to formalized TK for the developer. The book tells only part of the process with unclearly defined incoming steps and unclearly shown next steps. In itself, use case is most often not a complete statement for the developer.
Nevertheless, this is a very good way of formalizing and processing scenarios of the interaction of an object and a subject, when the interaction causes a change in something in the subject. It is one of the few recording methods that allow verifiable requirements with explicit exception lookup points.
The book is required to be read by analysts so that they begin to write verifiable productions.
What it is? This is a description of the scenario of user interaction with the system (or business). The system at the same time acts as a black box (and this makes it possible to divide the complex design task into designing the interaction and ensuring this interaction). At the same time, notation standards are introduced, which ensures ease of reading, including for non-participants, and allows you to make some checks for completeness and compliance with the goals of the stakeholder.
Use case example
What the scenario looks like, using the example of authorization on the site via email:
(System) Log in to the site to access your personal account. ~~ (sea level)
Context: An unauthorized client is authorized on the site so that the site recognizes it and displays personal information for it: browsing history, purchases, the current number of bonus points, etc., using email as a login.
Level: User Goal
Main actor: customer (visitor to our online store)
Scope: Customer interaction with the website of the online store
Interested parties and interests:
- the marketer wants the maximum number of website visitors to be identified to better reach personal newsletters,
- a security specialist wants to prevent unauthorized access to the visitor’s personal data, including attempts to select a password for one account or search for an account with a weak password,
- an attacker wants to gain access to victim bonuses,
- competitors want to leave negative reviews on products,
- the botnet wants to get the store’s customer base and use the attack to make the site inoperative.
Preconditions: the visitor must not be logged in.
Minimum guarantees: the visitor finds out the fact of a successful or unsuccessful attempt to log in.
Guarantees of success: the visitor is authorized.
The main scenario:
- The client starts authorization.
- The system confirms that the client is not authorized and does not exceed the number of unsuccessful authorization attempts from this session (search for a weak password for many accounts) according to "Security Rule No. 23".
- The system increases the counter of the number of authorization attempts.
- The system displays an authorization form to the client.
- Client enters email and password.
- The system confirms the presence of a client with such an email in the system and the password matches and does not exceed the number of attempts to enter this account according to Security Rule No. 24.
- The system authorizes the client, adds the browsing history and basket of this session with the last session of this client account.
- The system displays an authorization success message and proceeds to the script step from which the client interrupted for authorization. At the same time, the data on the page is overloaded taking into account the personal data of the account.
Extensions:
2.a. Client is already authorized:
2.a.1. The system notifies the client of the fact of the authorization made earlier and suggests either aborting the script or proceeding to step 4, while if step 6 was successfully completed, then step 7 is carried out with the clarification:
2.a.7. The system deactivates the client under the old account, authorizes the client under the new account, while the browsing history and basket of this interaction session remains in the old account, does not go into the new one. Next, go to step 8.
2.b The number of authorization attempts exceeded the threshold under "Security Rule No. 23":
2.b.1 Go to step 4, the captcha is additionally displayed on the authorization form
2.b.6 The system confirms the correct entry of captcha
2.b.6.1 Captcha entered incorrectly:
2.b.6.1.1. the system increases the counter of unsuccessful authorization attempts for this account as well
2.b.6.1.2. the system displays a failure message and returns to step 2
6.a. No account was found with this email:
6.a.1. The system displays a message about the failure and offers a choice of either a transition to step 2 or a transition to the “User Registration” scenario with saving the entered email,
6.b. The password from the account with this email does not match the entered:
6.b.1 The system increases the counter of unsuccessful attempts to enter this account.
6.b.2 The system displays a failure message and offers to choose either a transition to the “Password recovery” scenario or a transition to step 2.
6.c: The counter of attempts to enter this account has exceeded the threshold under the "Security Rule No. 24".
6.v.1 The system displays a message about blocking the entrance to the account for X minutes and proceeds to step 2.
What is great
Checks for completeness and compliance with goals, that is, you can give the requirements for verification to another analyst, allowing fewer errors at the stage of setting the task.
Working with a system such as a black box allows you to share the development and coordination with the customer of what will be automated from the implementation methods.
It is part of the analyst’s path, one of the main parts of usability. The user’s script sets the main paths for his movement, which greatly reduces the freedom of choice for the designer and the customer and helps to increase the speed of design development.
It is very pleasing in the description of the place where the exceptions of each interaction step are revealed. A holistic IT system should provide for one or another exception handling, part in manual mode, part in automatic (as in the example above).
Experience has shown that poorly thought out exception handling can easily turn a system into a terribly inconvenient system. I recall a story when in Soviet times it took several approvals from different services to get a decision, and it hurts when the last service says - and you have a wrong name or some other mistake in punctuation, redo everything and reconcile everything.
Often I encounter situations where the system logic that was not thought out for exceptions required a significant alteration of this system. Because of this, the lion's share of the analyst’s work is spent on handling exceptions.
Text notation, unlike diagrams, allows you to identify and cover more exceptions.
Addition to the practice method
Use case is not an independently prioritized part of the production, unlike a user story.
In this scenario, consider the exception “6.a. No account with this email was found. ”And the next step“ 6.a.1. The system displays a failure message and proceeds to step 2 ”. What of the negative remains behind the scenes? For the client, any return is equivalent to the fact that all the work that he has done entering the data is thrown into the landfill. (This is simply not visible in the script!) What can be done? Rebuild the script so that this does not occur. Can this be done? You can - as an example, look at the authorization script in Google.
Scenario optimization
The book talks about formalization, but talks little about optimization methods for such scenarios.
But it is possible to strengthen the method by optimizing scripts and the use case formalization method allows this. Specifically, for each exception that occurs, you need to think about it, determine the reason and rebuild the script so as to get rid of the exception or minimize the client’s path.
In ordering the online store you need to enter the city of delivery. It may turn out that for a city chosen by a customer, a store cannot deliver goods because it does not deliver there, due to overall restrictions or due to the lack of goods in the corresponding warehouse.
If you simply describe the interaction scenario at the design stage, you can write “inform the customer about the impossibility of delivery and offer to change the city or the composition of the basket” (and many novice analysts stop at this). But if there are a lot of such cases, then you can optimize the scenario.
The first thing to do is to give only the city where we can make the delivery. When to do it? Before the moment of choosing a product on the site (city auto-detection via ip with specification).
The second - you need to give a choice only of the goods that we can deliver to the client. When to do it? At the time of selection - on the goods tile and product card.
These two changes significantly eliminate this exception.
Measurement and Metric Requirements
Considering the task of minimizing the handling of exceptions, you can put the task on reporting (use case is not described). How many exceptions were, in what cases they occurred, plus how many scenarios were successful from incoming ones.
But alas. Experience has shown that reporting requirements for scenarios in this form are not enough, you need to consider reporting requirements for processes that are described mainly not in the form of a use case.
Usability Access
In our practice, we have expanded the use case description form with the description of specific attributes of entities and data for decision-making by the client, which enhances the subsequent usability.
For usability design, we added an input section - the displayed data.
In an authorization scenario, this is a fact of client authorization in the system. If the client is pre-authorized, then display a warning about switching the navigation history and the basket to the new account after successful authorization.
In the general case, this is a mapping of the necessary information for the client so that he can make a decision about his further actions according to the scenario (one may ask if the client has enough of this data, what else is needed, what information is needed for the client to make decisions).
It is also worth splitting the input information into the input fields if they are processed separately and with the formation of various exceptions.
In the example with client authorization, if you select the entered information with a username and password, then you should change the authorization script with the separate steps for entering a separate login and password (and this is done in Yandex, Google, but not in most online stores).
Access to the required data conversion
The requirements for data transformation algorithms can also be pulled out of the script.
Examples:
- To make a decision about purchasing a product in an online store, a client needs to know on the product’s card the possibility, cost, delivery time of this product to his city (which are calculated by the algorithm upon the fact of the availability of goods in warehouses and supply chain parameters).
- When a phrase is entered into the search string, the client is shown the search tips by the algorithm (which are formed by the algorithm ...).
Total
In general, after reading the book, unfortunately, it is not clear how to go the entire way of the analyst from business problems to formalized TK for the developer. The book tells only part of the process with unclearly defined incoming steps and unclearly shown next steps. In itself, use case is most often not a complete statement for the developer.
Nevertheless, this is a very good way of formalizing and processing scenarios of the interaction of an object and a subject, when the interaction causes a change in something in the subject. It is one of the few recording methods that allow verifiable requirements with explicit exception lookup points.
The book is required to be read by analysts so that they begin to write verifiable productions.
All Articles