04 What is the first thing to do after receiving a task? #

Hello, I am Zheng Ye.

Carrying on with the previous story, let’s continue talking about the programmer Xiao Li. This time, he received a new task of developing a single sign-on service. After several days of hard work, he successfully completed all the coding. Just as the product manager Xiao Wang passed by, he took the opportunity to ask Xiao Li.

Xiao Wang: How is the single sign-on feature coming along?

Xiao Li: It’s done. Let me demonstrate it to you.

Xiao Li demonstrated the functionality he had developed, and Xiao Wang seemed satisfied.

Xiao Wang: Well done. However, why isn’t there support for captcha?

Xiao Li: Why do we need to do that?

Xiao Wang: Isn’t it part of the login process?

Xiao Li: Where is it specified that we have to do captcha?

Xiao Wang: Nowadays, is there any login process without captcha?

I believe you have sensed the tension in the conversation. At this point, if both parties cannot control their emotions well, a physical confrontation may be imminent.

Why is there such a big disagreement between the two sides? One important reason is that both parties failed to clearly define the boundaries and requirements before implementing this feature.

Problem with Requirement Description #

In software development, what programmers do is generally defined by requirements. We all know that requirements are an important part of software development, but you may not have carefully considered that different ways of describing requirements can affect our understanding of them as programmers.

Because information transmission is subject to decay, it is impossible to transmit 100% of the information you understand to another person, and how to transmit it, that is, how to describe it, will directly determine the rate of decay.

In many companies, the software development model is based on a list of features, which “prescribes” the features that programmers need to implement. Each team receives a development list from the product manager and then begins coding “as instructed”. However, typically, these feature lists are just simple descriptions, and you cannot see the big picture.

A common state in many teams is that programmers know what features they are developing, but they cannot answer who will use these features and under what circumstances. If you ask them why they need to develop a particular feature, they usually say, “It is prescribed in the feature list.”

This type of feature list-style requirement description breaks down a complete requirement into fragments. It is only when all the features are developed and integrated together that the “broken pieces” are put back together.

In other words, until the very end, most people do not have a complete picture, which is equivalent to not seeing the complete “end”. If you continue along this line of thinking, you will encounter many unexpected problems at the last moment, leading to chaos.

Based on this feature list-based requirement description, each team arranges their work by prioritizing features according to their own understanding.

So, when your team completes a feature, it may not go live because you still rely on the work of other teams, and it happens that this team has just placed the related feature development at the end.

This is just the case when there are dependencies between two teams. If multiple teams need to collaborate, you can imagine how bad the situation can get.

Therefore, when we tell the product manager “we don’t have enough time, let’s cut some requirements”, the answer we get is definitely “I’m sorry, we can’t do that because the requirements are fragmented and cannot be adjusted.”

Therefore, some new ways of describing requirements have emerged, and among them, User Story is my favorite. It describes a desired feature from the perspective of the user, focusing on the path the user needs to take to complete an action in the system. Since it is a “story”, it needs to be a complete scenario that can be narrated.

What is the use of “User Stories”? #

Let’s take user login with username and password as an example to see what a user story looks like. A complete user story generally includes the following parts:

• Title: Briefly describes the main content of this user story. For example: Register users use username and password to login.

• Overview: Briefly introduces the main content of this user story. It is generally formatted like this: - As a (Role), I want to (Activity), so that (Business Value). - This means: as a certain role, what kind of action I want to perform in order to achieve a certain effect. The most important thing is to tell others why we need to do this. Although it is only one sentence, this is often a part that many people overlook. They only know what to do, but not why. - Here’s an example of an overview: As a registered user, I want to log in with my username and password so that I can access services that are available only to registered users.

• Details: Describes the complete process of this user story in detail. We will include information such as operation flows and user interfaces here. - For example: the user can log in successfully by using the correct username and password; if the password is incorrect, the login page will show a message saying “Username or password is incorrect”. Basically, when programmers see this part, they can visualize what the user story looks like in their minds. - Out-of-scope parts, such as third-party login, are mainly used to restrict people from going further.

• Acceptance Criteria: This part describes what a normal usage process looks like and how the system responds to various exceptional scenarios. This is something that programmers often overlook. It turns many narrative parts in the Details section into specific test cases. For example, here are two acceptance test cases: - Normal scenario: Given a registered user named Zhang San, whose username is zhangsan and password is foobar, when Zhang San logs in to the system using zhangsan and foobar, he can log in successfully. After successful login, he will be redirected to the user center. - Exceptional scenario: Given a registered user named Zhang San, whose username is zhangsan and password is foobar, when Zhang San logs in to the system using zhangsan and wrong, the login will fail and the login page will show a message saying “Username or password is incorrect”.

In the example above, the reason for the disagreement between Xiaozhang and Xiaowang about whether the requirements are complete is because everyone has a different definition of what constitutes completion of the requirements. So what can we do in this situation?

The theme of this module is “starting with the end in mind”. Now that you have seen how user stories describe requirements, you may already know what I’m going to say. Yes, a very critical point here is the “acceptance criteria”. Many people learn user stories and think that the most important thing is to remember the format of “As…, I want to…, so that…”.

In my opinion, regardless of which requirements description method you use, this part can also be clearly explained. So what can we learn from user stories? I think it is the key point of user stories: the acceptance criteria. It can clearly define the boundaries of requirements.

An important part of the acceptance criteria is the description of exceptional scenarios. Most programmers are good at solving normal flows, while exceptional flows are often easily ignored and become the key factor in disputes. Since disputes are likely to arise, let’s define it clearly from the beginning. What constitutes completion of the requirements is determined by the acceptance criteria.

After we say that our development is complete and can be handed over to the tester for testing, we need to demonstrate it to the tester in accordance with the acceptance criteria to prove that our system can indeed run smoothly. After that, the tester will take over the system and conduct more comprehensive testing.

The acceptance criteria provide the most basic test cases for the requirements, ensuring that the development team meets the minimum quality requirements of the requirements. If you are familiar with BDD (Behavior-Driven Development), you can write acceptance test cases based on the content provided in the acceptance criteria.

In actual work, many product managers have not figured out many details before handing over the requirements to the development team. Those functional list-style requirements often only include the normal path, and those missing details are completed by the development team in the subsequent process. User stories provide a fixed format for them to clarify these issues that should have been thought through.

If your team adopts the format of user stories for requirements description, that’s great. If not, supplementing the acceptance criteria in the functional list will greatly improve the efficiency of collaboration between the two parties.

Your Role #

You may have such a question: if the product manager clearly describes the implementation details of the requirements through user stories, where is the room for us programmers to exert ourselves? Please note that the implementation details provided by the acceptance criteria should be business-oriented, and it is a waste of time for programmers to think about this kind of problem. Our room for maneuver should be in technical implementation.

However, in reality, many teams cannot achieve this level.

You will find that one important reason why we are prone to make mistakes during development is that, due to the lack of certain aspects, we have to play many roles when developing a feature. One of these roles is the product manager. You are a professional programmer, but in most cases, you are just an amateur product manager, so it is inevitable to make mistakes.

You may say that you work for a small company that doesn’t have many people, and there is no dedicated product manager. There are only a few of us “in-demand” programmers, and the requirements are given to us by the boss. Who will help us write the acceptance criteria?

Unfortunately, the answer can only be yourself. Although you are a programmer in name, when you receive a requirement, what you need to do is not immediately start coding, but to play the role of the product manager, analyze the requirements, and define the scope of the task. Believe me, analyzing in advance is much better than handing a completed system to the boss, only to be told that it is not what he wants.

In addition, I want to remind you to pay attention to the fact that our thinking mode is different when playing different roles. Using the example of developing a username and password login, what you may think of is that entering the correct username and password allows for successful login, and entering incorrect ones should be denied with a prompt.

If you only play the role of a developer, thinking about these aspects is already good. But if you play the role of a product manager, you will think from the perspective of the product, and you will see different things, such as:

• Do we need a CAPTCHA for login?
• Do we need third-party login options?
• Are there any length restrictions on usernames and passwords in the system?
• Should passwords comply with certain rules?
• …

I know that if I ask you to fill in this list, it will be longer. Maybe not all of these functionalities need to be implemented, but from an analytical perspective, these are the issues we need to consider. A login feature is by no means as simple as just verifying usernames and passwords. We can think of these because we are playing different roles.

Therefore, if you want to juggle both the roles of a developer and a product manager, I suggest you first play the role of a product manager well, take some time to define the acceptance criteria, and then switch back to the role of a developer to write code. After all, the best code to maintain is the code that hasn’t been written.

Summary #

Requirements are a critical part of software development, and a failure to understand them properly can lead to significant waste. Traditional feature lists simply list the functions that need to be implemented, losing a lot of context and causing team members to only see the trees but not the forest when it comes to requirements.

In larger teams, a single feature may be divided among multiple smaller teams, with each person only seeing a fragment of the functionality. As a result, other methods of describing requirements have emerged, such as use cases and user stories.

In the actual development process, a lot of disagreements arise from the definition of “requirement completion.” Applying the principle of “beginning with the end in mind” to requirements, we can see that user stories have a very important component: acceptance criteria.

Acceptance criteria not only describe the normal flow of a feature but also address the handling of exceptional flows. They also serve as the starting point for acceptance testing. Once acceptance criteria are defined in advance, a lot of pointless arguments can be avoided.

Understanding the role of acceptance criteria, even if we don’t use user stories to define requirements, we can still apply the key points of user stories to our own practices by including acceptance criteria in the definition of each feature in the feature list.

If there is only one thing you remember from this content, please remember this: before working on any requirement or task, define the acceptance criteria first.

Finally, I would like you to think back to your actual work and consider how you clarify your requirements or the difficulties caused by unclear requirements. Please feel free to share your thoughts in the comment section.

Thank you for reading, and if you found this article helpful, please feel free to share it with your friends.