We at QIWI regularly hold meetings of analysts and project managers, where we tell each other about our experience, share our knowledge and useful techniques. At one of these meetings, I talked about the Use Case methodology and my experience of working with it. The story was met with a bang, and I decided to share it with the habrasoobschestvom.

I will use colloquial "use case" instead of clumsy tracing paper "use case". I hope, dear audience for this will forgive me.
Yuzkeysy became widely known according to the
book of Alistair Coburn, one of the authors of the Agile Manifesto. Russian translation of the book was released in 2002. In fact, the author of the methodology is Ivar Jacobson. He published it in the mid-80s, and began to develop since the late 60s. Subsequently, Ivar Jacobson, Grady Butch and James Rambo combined their approaches to the description of information systems, and the UML was born.
')
My relationship with user accounts began in 1996 and at first did not develop very well. I then worked at a communications company, and I had a free internet connection. According to the dylapu, through a telephone modem at 9600 baud, I plowed the expanses of the then Internet in search of a technique that would help me describe the functionality of an integrated enterprise information system.
The fact is that the automation of business processes there was implemented on isolated desktop applications with isolated databases. Up to the point that the accounting of individuals-subscribers and settlements with them was in one DB, and the accounting of corporate subscribers - in another. And nowhere was, for example, a pool of free telephone numbers. The task was to combine all this into a single accounting system for all services. What is now called "billing".
I did not know how to start formulating the requirements for such a large system, and began to look for a suitable way. I stumbled upon the UML specification version 0.9, which had just been released. I was delighted, with burning eyes, and read it from cover to cover. I liked everything wildly, I understood all the UML schemes and how to use them. Except one: Use Case diagrams. It was not clear what it was, why she was and how to apply it. Below I will explain why this happened.
The billing problem was finally decided - they bought from a third-party vendor, then they implemented it for several years. But by that time I was already far away. Yuzkeys did not learn to write then and, in general, did not feel much discomfort.
In 2004, I came to work as a systems analyst at one of the large outsourcing companies, where my real acquaintance with user cases took place. The development standard there was the Rational Unified Process, all functional requirements in all projects were supposed to be formulated only in the form of use cases. This, of course, is a radical approach; even then it seemed strange to me, and now I know for sure that this is impossible. Nevertheless, after listening to a couple of trainings and reading Coburn, I figured out the technique and began to apply it. Since then, user cases have been my favorite tool for analyzing and developing requirements.
What is yuzkeys?
There are different definitions, they at first glance vary greatly. The most vague is found in Coburn, he defines the use case as "an agreement on the behavior of the system in question." True, Coburn had a whole book to reveal and clarify his definition.
And here is the definition from the UML glossary (my translation).
Yuzkeys is a description of a set of sequences of system actions, including variants of such sequences, as a result of which an observable result is obtained that has some value for some of the participants in the process.What definition do I try to keep in my head when I write a user case? It should tell me what I should do, what I need to remember to write:
Yuzkeys is a text
script description
interaction with the system
leading to a meaningful result .
It is short and that is good. But it has several implicit defaults. About which I also remember, developing a yuzkeys. Here is the full version:
Yuzkeys is a text
scenario description (maybe not one)
interactions (who or what?) with the system,
leading (possibly not leading)
to a meaningful (for whom?) result .
This definition tells me that from the description of the user case should be clear:
- Result - spelled in title
- What is the system in question?
- Participants of interaction (actors: people, external systems, who is the main participant?)
- Sequence of actions
- At each step: Who? What is he doing?
- What happens if something goes wrong?
For example, I will cite a user from a real project. In 2012, QIWI Wallet became a multi-currency one, and conversion rates were first set based on the Central Bank rates. But then they decided to install them on the market, and the project was devoted to this transition. Yuzkeys pretty simple. The trader exposes courses in the ABS - automated banking system. The treasury director or his deputy must confirm them just in case. Suddenly, the trader will make a mistake: the hand trembles, the wrong number will hit. The price of a mistake is great. If something is wrong, the director rejects the application, and the trader does the work again.
Installation of courses for QIWI Wallet usersMain script- Trader creates a request for installation courses. The application provides all initial purchase and sale rates on the list of quoted currencies, as well as the date and time of their entry into force (see the application form).
- The Treasury Director receives an email about the need to confirm the application.
- The director reviews the application and approves it (see approval form).
- The ABS stores courses for use in the QIWI Wallet from the time specified in the application.
- Interested parties will receive an e-mail message indicating the new courses and the date / time of their entry into force.
Rejection of application- In step 3, the director rejects the application.
- The trader receives an email about the rejection of the order.
What is not needed in the yuzkeys
Kobern does not hide that his favorite format of the yuzkeys is Fully Dressed (how is it, in Russian, overdressed?). In addition to the main and alternative scenarios, it includes sections:
- Context of use
- Scope
- Level
- Main character
- Participants and interests
- Precondition
- Minimum guarantees
- Trigger
- Extensions
- List of changes in technology and data
In my experience, nothing is needed. All this only makes it more difficult to start reading the script and understand the essence. I have never had to write a completely oversized yuzkeysy. The closest thing to this was one project, which was done for two years, and it never took off.
Developing a junction case, you should not impose premature restrictions on the design. Take a look at the case above. There are no details of the screen forms and control elements of the interface. The user will select an option from the drop-down list, by selecting an option or pressing a button? It does not matter now, decisions of this level should be postponed until later. Do not do the work of a designer, he will make it better than you.
You say: well, of course, that you have written that the director receives an
e-mail notification . And why not by SMS or in some other way? Because at that time we already agreed with the users on the e-mail address. If I wrote in the abstract, they would be perplexed: how could it be, didn’t we decide that it would be an e-mail? Something has changed? Having described the user interface in a little more detail than it should be according to the method, I took care of the reader so that he would not stumble while reading the case.
In general, when choosing information for inclusion in the use case, the main criterion should be the
ease of perception . For her, you can sacrifice the rules, detail, sometimes even accuracy. The main thing is that the user case is clear on the go. If it is difficult to understand it on the go - this is a bad use.
What else is missing from the above example? There is nothing about how courses are transferred from the ABS to the QIWI Wallet processing system. Because it is the subject of another interaction and another yuzkeysa. If, due to some kind of failure, the courses do not reach processing, this is not a trader’s concern. For him, the result is achieved: the courses are assigned and approved.
Do not try to push everything into one piece of software. Differentiate them based on user goals.
Conditional constructions
One of the basic requirements of Coburn is the absence of branches in the script. If there is an alternative scenario, it should be described separately. Any arbitrarily complex block diagram with branches and cycles can be represented as a set of linear sections.
I do not always follow this rule. I admit, I corrected my use case before putting it here as an example. And in the original, he looked like this. Differences begin with paragraph 3.
Course Setup Script- Trader creates a request for installation courses. The application provides all initial purchase and sale rates on the list of quoted currencies, as well as the date and time of their entry into force (see the application form).
- The Treasury Director receives an email about the need to confirm the application.
- The director reviews the application and approves or rejects it (see approval form).
- If the request is rejected, the trader receives an email about the rejection of the application.
- If the application is approved, then:
a. Courses are saved for use from the time indicated in the application.
b. Interested parties will receive an e-mail message indicating the new courses and the date / time of their entry into force.
I believe that if in the scenario one or two branches, small and without nested conditions, the use of conditional sentences will only improve readability.
Business rules
How to combine the conciseness of the use case with a lot of details that are usually needed to design the user interface and develop the code? To do this, I accompany the case with a list of business rules that should be considered when implementing scripts.
Here are the business rules that were attached to the use case from the example.
- The time of entry into force of the courses can only be 12:00:00, 16:00:00, 20:00:00.
- The trader is allowed to submit an application for approval no later than 45 minutes before the courses take effect.
- The trader can delete the order if it is not yet submitted for approval or rejected.
- A trader can edit an unsent or rejected order and resubmit it for approval.
- A trader can create and submit for approval several applications with different dates and times of entry into force.
- Saving another application with the same date and time as an existing one is impossible.
- The director may approve the application no later than 40 minutes before the courses take effect.
- The director may remove the approved application, but no later than 60 minutes before the courses take effect. New courses specified in the application, in case of its removal do not take effect.
- When an application is deleted, a message is sent to interested parties about the cancellation of the installation of new courses.
- It is necessary to keep in the log information about the following user actions: submitting an application for approval, approval of an application, deletion of an application. For each of them, the following must be saved: date / time of the action, user, application data: initial rates, date and time of entry into force.
- If QIWI Wallet processing could not load courses at the right time on a schedule, then, in addition to notifying operating specialists, a message should also be sent to the list of interested parties.
If you look closely, then almost every one of the rules can give rise to another alternative scenario, or even a whole user case. For example: "The director did not have time to approve the application." But if I painted all the alternatives, as it should be for Coburn, yuzkeys would become worse. It would be harder to understand and highlight the essence.
You should always carefully evaluate which details should be included in the scenarios and which should be included in the list of business rules.
When multiple systems
One of the central concepts in the topic of uscase cases is the “system under consideration” (SuC, System under Consideration, or SuD, System under Development). According to the classical approach, there is a system that we are developing, and it has a boundary. Everything in the universe is divided into what is inside the system and what is outside it. And we consider only those interactions that go across the system border. Knowing that at the entrance and at the exit we can decide how it should work inside.

This approach can be called "unicellular". We focus on what happens in the cell membrane and ignore everything else for the time being.
But in reality we live in a multicellular organism. The company has many systems, they interact with each other and jointly implement many functions of the business. In almost every project, we must meet the next need of the company through making changes, if possible minimal, in several systems.

For Cobern, this is provided for, there is the option “Organization - Transparent Box”. But he has this somehow in passing. Basically the story goes about how to describe the only system in question in the form of a black box.
I prefer not to distinguish between the systems to which we set the requirements and external actors in my own use cases. Each of the systems that we modify is considered the same participant in the interaction, like all the others. From the point of view of the classical method, this is not possible: the system is what is inside, the actors are what is outside.
But my approach allows us to extract a set of functional requirements for each system separately. We take all the steps of user cases in which this system participates. We look, whether it is existing functionality or new, or existing, but with some changes. Steps in which there are no changes, we throw it out. What remains is passed on to the system development team for detailed technical study. Repeat for each of the systems involved in the project case.
Predictable without a subject
From time to time in scenarios one encounters the following phrases: “the data is stored in the database”, “SMS is sent to the user”. There are no actions that are performed by themselves. They are always done by someone or something.
I fully agree with Coburn’s recommendation on the structure of sentences in the script. Each step of the use case must begin with the subject — who or what performs the action. Then the predicate is what action. Then everything else. The predicate must be in the present tense and in the actual voice. "The user chooses a settlement", "The application shows a list of goods."
Having looked through the initial words of the steps, it is easy to collect a list of participants. I prefer not to write out separately the list of participants at the beginning of the use case, this slows down the reader and prevents him from moving quickly to reading the script.
Unsuccessful scripts
Sometimes projects forget to foresee cases when something is wrong. For example, a customer made a purchase, and then wanted to return it. If you didn’t think about it beforehand, then you have to finish the code immediately after launch. And in severe cases - throw everything away and organize the interaction of the systems in a different order.
The technique of use cases helps (though not guaranteed) to avoid such complications. Having written the main script, think: what can go wrong on each of the steps? What could happen elsewhere after everything is over here? Each variant of deviations found must be written out, to begin with at least one phrase. Then, if necessary, work through the steps.
If the project describes only the main scenarios of user cases, then there is a risk that they have forgotten something important.
Domain Model
User cases should be based on a domain model, which all project participants understand in the same way. Let us recall the first step of our example: “A trader creates an
application for installing courses . The application provides all
initial purchase and
sale rates on the list of
quoted currencies , as well as the date and time of their
entry into force (see the application form). ” In one paragraph used five concepts. Some of them are new, appeared only in this project.
The most famous introduction tool in the subject area is the glossary. It should include in the glossary only those words that someone may be incomprehensible. If you begin to explain everything, then after the first three points the reader will become bored and he will close the glossary without reaching the important point.
You can write short articles explaining new concepts. Here is an example - an excerpt from the documentation of the same project:
Supported currenciesThere is a list of supported currencies. This list is divided into two parts:
- Currencies wallets - in which customers can open wallets.
- The rest (“payment currencies”) - clients cannot open wallets in them, but in these currencies payments may be indicated.
The list of supported currencies may eventually expand, the currencies of payments become the currencies of the purses.
For each currency, it is also known whether it is quoted against the ruble or the US dollar. “Quoted” in this case means “the rate is set by the Treasury”.
(We believe that the dollar is quoted against the ruble, but not the ruble against the dollar, since the dollar is set in rubles, and not vice versa).
Another classic way of describing a domain model is “entity-relationship” diagrams in IDEF1 or static UML structural diagrams.

In one recent project, I set out a model of the subject area on such pictures an hour a day, for two weeks, to the development team. As a result, all developers had a single picture of concepts, which helped us a lot during the project.
List of user cases
If requirements are described in the form of user cases, their list becomes a useful project management tool. For example, in the list of user cases, you can prioritize implementation, you can measure progress by the number of implemented user cases. The list of user cases can exist in the form of the actual case (Use Case Survey) or in the form of a diagram of user cases.
Here is a list of yuzkeys from another project, it is also about currency conversion. The payment system calls the bank to exchange currency for an amount that is enough for the holders of foreign currency wallets and payees.
- Set turn prediction
- Create conversion requests
- Send applications to the bank
- Execute conversion requests
- Take into account completed applications
The same list, but in the form of a diagram yuzkeysov.

There is more information here: we see the participants of the interaction and in which user cases they participate. Contrary to Coburn, the participants are shown the systems to which we put requirements (settlement system, ABS), as well as external immutable systems (exchange terminal, accounting system) and users.
Now I can explain to you why the uskase diagram was not clear to me when I first met UML. The fact is that all the other UML diagrams model the
system , they show it to us from different perspectives. A user diagram does not illustrate the system itself, but a
set of functional requirements for it. Yuzkeys diagram, therefore, - model model. It was not so easy to understand right away.
Conclusion
Yuzkeysy - already quite old methodology. Over the past 20 years, new approaches have emerged, which have suppressed the technique of use cases in those areas in which it was once the best. For example, user stori allow you to more effectively manage the requirements in Agile-projects. User experience design techniques help develop products that are successful in the market. In my opinion, today, in comparison with more modern methods, user cases are approximately in the same position as the flowcharts in their time compared to user cases. The good old flowcharts — now the Activity diagrams in the UML — are still being used. But once they were considered a universal way of designing and describing programs, and then their use narrowed with the advent of techniques such as Use Case, UML, BPMN.
Nevertheless, the use cases still remain a good analysis tool, especially for systems supporting business processes. Any analyst or project manager should know the method of use cases and be able to use it. This is, in fact, my post.