Transcription
Good afternoon, my name is Alexander, and I am a business analyst. Today, I will present a report on how to write requirements for a website in a way that the team will want to read them. My presentation is primarily aimed at beginners, specifically those with about 0 to 2 years of experience.
I will focus on a project that Iena talked about in her first report, where we need detailed documentation because, for example, the team may change, or the logic may shift. Have you ever heard of the problem where developers do not read requirements? This issue has been discussed at various stages, and even at this stage, we received such information.
All business analysts approach this differently. Some apply brute force, while others believe that it’s better not to write requirements at all and rely on live communication. However, we will try a different approach: we will write requirements in a way that makes them easy to understand and read.
Based on my personal experience, I can highlight three key pieces of advice.
First, develop a clear terminology for the domain.
Second, explain the user’s goals.
Third, highlight atomic acceptance criteria.
Starting with the first point, we must understand that developers do not want to be translators. If they wanted to be translators, they would have gone to university, received a linguistics diploma, and would not be working as business analysts. What this means for us is that the terminology we use in requirements should ideally match the terminology in the code and the database.
At the beginning of a project, a business analyst should conduct a domain analysis and clearly identify all entities, their properties, and the actions performed on them. This is necessary because all modern programming languages evolve within the object-oriented paradigm. We need to think in terms of objects.
For example, as a user, I am an instance of the user class. I have certain properties, such as my real name, date of birth, username, password, and last login date. There are also actions that can be performed on me, such as creating, editing, logging in, and deleting.
The most valuable thing a business analyst can do for developers is to identify all these entities, their properties, and actions at the beginning of the project. This way, the classes, fields, and methods in the code will correspond to the tables and columns in the database.
For instance, in an online store, we can identify an entity like an order. Within it, we can highlight attributes such as the buyer's status and the time of the order. We can also identify actions like creating, viewing, editing, and deleting an order.
Let’s consider an example: a client tells the business analyst that they want to see if a buyer has paid for a product. It would be a mistake for the business analyst to take this request literally and write it down as a requirement. In the context of an online store, the term "product" is very ambiguous. It could refer to a product that can theoretically be produced and sold, a unit of inventory that is physically stored in a warehouse, or products in transit that have been shipped and are being transported to the buyer.
These are three different entities that need to be distinguished. If a developer reads such a requirement, they might think it refers to inventory units and add a property for "paid." However, buyers do not purchase all products in stock; they only buy part of it. With this database structure, it will be impossible to implement this feature, and this misunderstanding may be realized too late, causing release deadlines to be missed.
If the business analyst clarifies that the system should show only those products that have been paid for, that’s an improvement. This introduces the concept of a delivery unit, which relates to the payment status. This clarification allows for the implementation of the feature, but it raises another issue of duplication. An order can contain multiple products, and the property "paid" is actually a property of the order, not the product, as our product owner mentioned at the beginning.
Therefore, we can rephrase it: for each order, the system shows whether it has been paid or not. This is better because it correctly identifies the entity and its properties. However, the property "status" may also be needed for other accepted orders, such as whether they have been delivered. Even a delivered order may not be paid if the business model allows for it.
For payments, additional information may be required, such as from which account and for what amount the payment was made. A more accurate formulation would be: for each order, the system shows whether a payment has been made. This leads to the introduction of another entity, "payment," with corresponding properties.
When developing requirements and domain analysis, creating a glossary is very helpful. Again, taking the example of a purchase order, we have two alternative definitions on the website. Look at them and identify the differences.
In the first definition, we see vague wording, describing it as a request from one party to another. It’s unlikely that anything like this will appear in the code. We see a list of actions in this business process: buy, sell, deliver, receive. This is a description of the business process, not the entity itself.
In the end, there’s a legal formulation about agreed conditions, which is not specific to this company’s business model. The second definition reflects the specific properties of the entity. From the system's perspective, an order is a combination of the buyer, products, and price. This is what should be reflected in our requirements.
In summary, regarding the first piece of advice, my main conclusion is that a business analyst should not start writing acceptance criteria until they have conducted a domain analysis. When I join a new project, I spend the first week analyzing the domain, identifying entities, properties, and actions. Only then can I write requirements that are ready for use.
We need to avoid synonyms because there are no synonyms in code or databases. If you say "order a product," you shouldn’t say "reserve a product" elsewhere if you mean the same thing. Creating a glossary will help with this.
I personally highlight terms in this way: all entities and their attributes are marked with capital letters, like "Customer" and "Order." This way, when I say "Customer," I mean the same thing as in any other context. If I mean something different, I need a different term. This serves as a reminder for me.
Moving on to the second piece of advice: explaining the user’s goals. This means we need to clarify why and who will use the feature we are developing. It may seem unnecessary to write specifications purely as system requirements, but explaining the user’s goals is very important.
It helps engage the team in writing requirements. When the team understands the purpose of a feature, they can identify any shortcomings or deficiencies in the requirements and discuss them. This allows us to create complete and accurate requirements earlier than we would otherwise.
It also gives the team a sense of ownership in the project. Everyone enjoys contributing to the development of the product, which fosters the generation of new ideas and improves the psychological climate within the team.
Explaining the user’s goals also makes the requirements easier to read. For example, I think no one will be surprised by the classic template of a user story or preamble.
As a user of this system, it would be good to clarify the user’s role and state: "I want to have this feature or functionality so that..." Here are some examples using this classic template.
In the first example, as a user of the system, a manager or buyer wants to be able to print an order to sign it, stamp it, and hand it over to accounting.
In the second example, we discuss logging in before the user has logged in, which is a lesser role. It would be preferable to describe it in this way.
I have seen cases where all user roles in the system were attempted to be listed, but that’s not our case.
In this slide, I slightly deviate from the template. In the first case, as a user of the system, a buyer wants to be able to cancel an order they made because they no longer need those products. Here, I have revealed not just the user’s goal but the reason behind it.
Another interesting example involves the system logging any user actions on any orders. This simply accumulates in the database and does not reflect on the UI. There are no users in the system who can gain real benefits from this feature, but there is a benefit for the product owner, primarily for the client.
So, we can explain: as a system administrator, I want to see this history so that I can resolve complaints about undelivered orders, damaged goods, etc.
In addition, I often find it necessary to explain within the text why a certain acceptance criterion is needed. For example, if we need unique phone numbers, the team may wonder why. We can clarify that it’s because our clients provide their landline numbers, not just personal mobile ones.
Sometimes, we may need a large field size on printed reports, and we can explain that this size is required by law because the report must be printed on a company letterhead.
In cases where forums leave more room for comments, questions may arise about the size of a field. Here, information about what will be written can help. If we explain that, for example, a courier will write why they couldn’t deliver an order, we can determine the necessary size for that field.
Now, let’s move on to writing atomic acceptance criteria. Here, I suggest recalling how the word "analysis" translates from Greek. Does anyone remember? Analysis means to divide or dissect.
What this means is that when an analyst works, they take the tangled wishes of users and extract structured requirements and independent acceptance criteria that are very small. This is their job.
The tester then synthesizes these atomic acceptance criteria into scenarios that will form the basis of test cases.
Let me clarify what I mean. I often see requirements written like this: "The system allows the user to add more than one product to the cart from the available stock." This is clear and concise, but it contains two different requirements: that more than one product needs to be added and that these products must be in stock.
These need to be tested separately, so they should be written as separate acceptance criteria.
If a product is on sale, the system shows the discounted price and highlights it in a special format. Here, the conditions are essentially the same, but the requirements involve two different data points we are showing and which system applies. It’s better to separate them into two distinct points.
Writing acceptance criteria in a positive tone helps make them easier to understand. For example, we could write: "If the user enters at least one character in the field, the system shows the options and a message."
This raises a reasonable question: what should the system do if it doesn’t show anything? Therefore, it would be more accurate to formulate it as: "If the user leaves the field empty, the system shows the options and a message."
Here, we have a case of double negation: "If the user has not selected any product, then the system does not allow placing an order." It would be better to say: "If the user has selected at least one product, then the system allows placing an order."
We removed the negation entirely, making it clearer and shorter.
In my practice, I often have fairly lengthy stories because my team finds it convenient to work that way. This is not a classic user story, but I frequently need to provide context for a specific acceptance criterion.
This need arises when a user interacts with the system under certain conditions that affect the system's response. For example, I have seen requirements written like this: "The system applies a discount coupon if the user provides it."
The system does this only if the user is verified. Here, we have a second thought that contradicts the first. To avoid this, we can use scenarios like: "Assuming the user is verified, if the user enters a discount code, then the system applies it."
This template allows us to clearly know where the system's actions are and where the response is.
Or, if the phone number is new, then the system sends a verification message. Here, we don’t see the context of what is happening.
To provide that context, we can write: "Assuming the user has enabled notifications, if the user edits their profile and saves the phone number, then the system sends a verification message."
Continuing from the previous report, I believe we need to describe in the requirements what the system should do and what it should not do.
It should not do something because it falls outside the scope of this story or is not part of our system at all, or it may belong to another story or be left to the developers' discretion.
For example, if you have a text field and you diligently ask the product owner whether this field should support Chinese characters, and the product owner says that they don’t have Chinese clients, it doesn’t matter to them.
If you write that the system should support Chinese characters, it may create confusion for developers about whether they need to change the encoding. If you write that the system should not do this, then developers will have to ensure that it doesn’t accept any Chinese characters.
This is not what the product owner wanted. I usually make comments within the text to clarify what is allowed and what is not, depending on what is easier for you.
The same applies when we have certain assumptions or, conversely, no assumptions in the system. For example, if the system allows unverified users to log in, this may not meet the team’s expectations.
When I describe the conditions under which the system allows login, I simply won’t mention whether users are verified or not because that condition does not exist. However, we should provide clarification that the system should not allow this.
In conclusion, I have a template for how I format my user stories. This closely resembles what was presented in the first report by Iena. I also create a separate page for the conference and link to an article in Jira.
I write the description and preamble in the same way. However, we probably don’t have time to go into detail. As far as I know, the organizers will publish the presentation on the website, so you can review how I format everything if you’re interested.
That’s all from me, and I would be happy to answer your questions. [Applause]
How to make developers want to read? Even your developers might read a bit more. I have a good team, but I’ve been in situations on several projects where, when I first joined without any experience, I approached a developer and explained what I had written. They told me, "Well, I never read. I glance at it with one eye."
Two months later, our conversation was different. They said, "I read your requirements." That’s why I felt I had the right to share my experience. Thank you for your attention. [Applause]