User Story Writing Guide: Crafting Stories Closest to User Real Scenarios

User stories serve as a form of expressing requirements in software development, providing a simple way to define what users want. Through them, a product can be clearly articulated. A good user story helps stakeholders understand the product's functionality and aids in introducing the product to customers. User stories are commonly written, but how can we write stories that are closest to the actual user scenarios?

I. Basic Expression of User Stories

To standardize the expression of user stories for effective communication, they typically follow this format: As a "user role", I want "to perform an activity", so that "I can achieve value". A complete user story should contain three essential elements:

• Role (who): Who wants to use this.
• Activity (what): What activity needs to be completed.
• Value (why): Why is this necessary, and what value does it bring.

For example: "As a ZenTao user, I want the board to adjust column width adaptively without filling the entire screen, so that it saves space, is convenient to operate, and appears more aesthetically pleasing and concise."

In addition to format standardization and completeness of elements, a good user story should also follow the INVEST principle.

II. Guidelines for Writing Good Stories

A good user story can be understood by everyone in simple language, serving as a medium for communication between technical and non-technical members. How can we write a good, easily understandable, and excellent story? Here are some key points to consider:

1. Start with Goal Stories

For some large projects involving multiple user roles, it can be challenging to identify where to begin in recognizing stories. To identify stories, consider each user role and their objectives in using the product.

For example, in developing a job search website, the role is the job seeker, whose objective is to find a job (the primary goal). We can understand this as: what features can support the job seeker in finding a job. Then break it down into several sub-goals:

• Search for jobs of interest (based on skills, salary, and location, etc.).
• Automatically execute searches so manual searching is not necessary every time.
• Make the job seeker's resume visible so that recruiting companies can find them.

After dividing it into sub-goals, additional stories can be derived as needed. For instance, recommending positions in corresponding areas based on location. This gradual clarification of writing stories becomes evident.

2. Write Closed Stories

Closed stories refer to meaningful goals being accomplished as stories are implemented, making users feel that they have achieved something.

For instance, in the job search website project, one story could be "Recruiters can manage their posted advertisements." This is not a closed story because it is an ongoing activity. How can we write it better? It could be:

• Recruiters can change the deadline for job advertisements.
• Recruiters can delete applications that do not match the job position, and so on.

3. Include User Roles in Stories

If the project team has identified user roles, then these specific roles should be used when writing stories, rather than more general roles. For example, instead of writing "Users can publish their resumes," it should be "Job seekers can publish their resumes." Because "users" encompass both "job posters" and "job seekers," this increases the difficulty of understanding the requirements for development.

We can use the expression format mentioned earlier: As a "user role", I want "to perform an activity", so that "I can achieve value". This will help differentiate between important and valueless stories and provide greater clarity.

4. Don't Over-Rely on User Stories

While user stories are a common way to collect and express requirements, they are not the only method. Depending on the project, teams can combine other methods to ensure comprehensive and accurate capture of requirements, providing a more complete perspective to meet specific project needs and requirements.

5. Write Stories for One User

When writing stories for a single user, they are usually easier to understand, read, and are more specific and clear. However, not all stories will differ based on the number of users. For many stories, whether written for one or multiple users, the content may not vary significantly. However, for some stories, the number of users involved may make a significant difference. For example, take the story "Job seekers can delete resumes from the website." It has two interpretations:

• One job seeker can delete their own resume;
• One job seeker can delete someone else's resume.

By considering a single user's story, the issue becomes clearer. For example, the story could be revised to "A job seeker can delete their own resume."

6. Use Active Voice

When writing user stories, use active voice instead of passive voice to make the stories clear, concise, and easy to understand. For example, "Resumes can be published by job seekers" can be changed to "Job seekers can publish resumes."

7. Customer Writing

Ideally, customers should be involved in writing stories. Customers are responsible for determining the priority order of stories for each iteration, so their understanding of each story is crucial. To ensure that customers have a full understanding of the stories, they can be directly involved in writing them, also to avoid understanding biases or misunderstandings that may result from stories being written solely by developers.

8. Don't Forget the Purpose

When writing, remember that the purpose of stories is to facilitate dialogue, ensuring that they can trigger discussions and exchanges about specific features or requirements. To achieve this goal, user stories should be concise and clear.

III. Final Exercise

Suppose the story "Job seekers can search for unfinished jobs" is too large and not suitable for completion in one iteration. How would you break it down?