At KiZAN, my team has iteratively developed an approach to user story titling that has helped us to better communicate the general meaning of a user story in a concise manner. Like many organizations, we lived for a long time with concepts such as user story titling becoming tacit knowledge – the longer you were on the team, the more you understood our user story titling conventions. In this post, I will share our philosophy on user story titling.

Before I begin, I want to give credit to David Bjarnson, co-worker and business analyst. David’s help bringing this information together, and driving us to document our team’s thoughts has been invaluable.

Philosophy

Our team philosophy on user story/product backlog item creation starts with the concept of at least one story per requirement. By this we mean that every requirement from a client must have at least one user story/product backlog item.

In most cases, stories also map directly to actions that can be performed in a system. For example, “Add a User”, “Update a User”, “Delete a User”, Print a Report, Export Data to a PDF, etc.

When authoring stories, we have several story categories regularly encountered. Based upon each category, a specific naming convention for the title and contents within the description are expected. If these conventions are followed, it eases the development and implementation process. The story categories are: Management, Reporting, Workflows, Dashboards, Calculations, and Action/Activities.

Story Titling Conventions

The general form our story titles following is [High-Level Feature] – [Mid-Level Feature] – [Feature Activity] – [Activity Modifier].

This form is meant to provide a hierarchy of more refined functionality within the title. For example, a story titled, “Widget – Setting – Add” suggests there is larger feature of the system named “Widget”, which has sub features pertaining to a “Setting”, which in turn has activity of “Add”.

Benefits of This Approach

There are multiple benefits of titling the story in this way. The most obvious is enhanced readability. By reading titles left-to-right, you always know you’re drilling down from a higher-level concept into a more detailed concept, i.e., “Widgets have Settings that you Add”. Conversely, reading the story title from left-to-right provides an easy way to articulate in normal sounding language what you’re trying to convey in the story, i.e., this story is about “Adding a Setting to a Widget”.

A second benefit of story titling in this manner is to allow easy sorting and grouping by the story title. If I had hundreds of stories, sorting by the story title can easy group all stories with similar names (and closely-related functionalities) together.

Drawbacks of this Approach

In big “A” Agile world, user stories should be concise, giving you just enough information to get started, force you to get up, walk over to your product owner/stakeholder/end user, and ask questions. This is big “A” Agile world.

Stakeholders aren’t usually available. We can’t always just get up and talk to everyone. Our team has to live in reality world. What does that mean? Reality world means, we never have enough information, and when we finally get stakeholder time, we need to be organized, time-efficient, and succinct. These reason have pushed us to be more detailed in our stories, using our stories to clearly document a single action/functionality. We still have iterative changes that occur, based on regular feedback, but the feedback is more pointed.

One of our drawbacks is granularity. Our user story titling conventions tend to err on the side of more granular, leading to larger backlogs and perhaps less flexibility on the implementation side. Management of the backlog and initial authoring also takes more time, but we hope the time spent articulating the requirements of a system can make development faster. We’re not really sure, but we’re adjusting our approach as it makes sense with each new project.

Common User Story Categories

The following sections identify common user story categories we employ in many projects. This is not a comprehensive listing of categories; however, you can use these stories as examples for deriving additional categories.

Assumptions

When authoring stories, persisting entered data (or “saving”) is always assumed. As a result, we do not explicitly say in a story title that information needs to be saved. For example, if you have a story describing that a user wants to “Add a Widget”, it is assumed that the story’s technical implementation will save this widget for future use in some sort of database or data store technology.

Base Pattern

The Base Pattern is not really a category, but a technique used regularly during backlog grooming. As we begin to decompose Features into stories, and further into sub-stories, we always begin with a Base story. The Base pattern simply describes an incremental approach to decomposing stories by adding a hyphen and giving more detail. In each of the following categories, we’ll describe how the base pattern may be used in backlog grooming.

Management

Many systems have standard data-entry “CRUD” (Create, Read, Update, Delete) requirements, where you are “CRUDing” an entity/object, such as Users or Accounts or Widgets. As a result, we have conventions and a standard set of stories typically associated with CRUD requirements. Because “CRUD” isn’t a glorious (or friendly name), we call these stories “Management” stories, i.e., User Management, Account Management, Widget Management, etc.

The basic convention is to title the backlog item leading with the entity and management (“entity” Management). The title is further broken out to what portion of management you are trying to perform (Create, Update, Delete, View/Read, etc.). Finally, actions are further broken out if needed. So, as example backlog items to manage users, you would have the following titles:

User Management – View

User Management – View – Print to PDF

User Management – Detail

User Management – Detail – Print to PDF

User Management – Create/Add

User Management – Create/Add – Validate

User Management – Create/Add – Notify Email

User Management – Delete

User Management – Update

User Management – Update – Validate

User Management – Search

User Management – Search Results

As you can derive above, you can see the relationship between each product backlog item by looking at the title. Each hyphen denotes a subcategory of the previous hyphenated item. So, View is the base user story followed by sub stories like Print to PDF, and Detail.

Base Pattern Usage

The base pattern is often used during grooming of Management stories. Below, we’ve outlined a logical progression of stories decomposed from a starting point of “User Management”.

Backlog Grooming Iteration #1

In the first grooming, we start with identifying the features, you can simply capture a single story for User Management:

User Management

Backlog Grooming Iteration #2

In the next grooming, we break out the base pattern story into several parts. The customer wants to view and add users, so we end up with two stories:

User Management – View

User Management – Add

The View story has details on the data fields important to see when viewing users. The Add story has information on the key data fields when adding a user. Basic required fields can be incorporated into the Add story, but more complex validation logic should be broken out into a separate story.

Backlog Grooming Iteration #3

In the next grooming, we receive more details on an action that needs performed when viewing users, emailing the user list to someone. As a result, we consider the View story as another base pattern, and further decompose into the primary view story and a second story for emailing the collection of users.

At the same time, we find there is complex validation logic related to a user’s First, Middle, and Last Name – we want to ensure no other users have an identical First, Middle, and Last Name; however, we only want to take into account the first letter of their middle name if a middle name exists. We now consider the Add story as a base pattern and add additional stories for clarifying validations.

These two changes decompose into the following stories:

User Management – View

User Management – View – Email

User Management – Add

User Management – Add – Validate Name

Decomposition Guidelines

Because management stories are fairly straight-forward, there is often not many iterations of decomposition.

You shouldn’t decompose Add/Edit/Update stories when you need to provide basic validation requirements, such as required fields, data type formats, or data field length restrictions. These can be built directly into the story description, if it is necessary. However, if validation becomes more complex, as in the previous example, an additional story can be added for clarification.

If additional workflow/system actions must take place as the result of performing an Add/Update/Delete action, a separate “After” story should be added to capture the intended flow of requirements. For example, if a user should receive an email if their email address is updated, then a separate story should be broken out, i.e., User Mgmt – Update, User Mgmt – Update – After Email.

If additional actions are capable from a story’s existing context, then a story should be decomposed. As above, then we broke out the Email functionality form the User Management – View story, a second story was created to capture this additional requirement.

Dashboard

Dashboards typically have multiple sections of grouped information for the user to view, or quickly utilize. As such, it each section of the dashboard is handled as its own user story, but related to the overall base user story that deals with the full view of the dashboard. The naming convention for Dashboards typically is the following:

Dashboard – View

Dashboard – View – Subsection 1

Dashboard – View – Subsection 2

Dashboard – View – Subsection 3

Dashboard – View – Action 1

Dashboard – View – Action 2

Dashboard – View – Action 3

Base Pattern Usage

Dashboard analysis and design is typically very iterative and typically requires more exploration and prototyping to better understand the true intent and usage context for users. As such, the Base pattern approach works well in decomposing dashboard sections.

Our approach to using the Base pattern technique begins with the Dashboard View, as sections of the Dashboard are refined, we decompose the details of that section into a separate story. For example, a Dashboard with a section dedicated to User Login Metrics and a section dedicated to Password Reset Metrics would decompose into:

Dashboard – View

Dashboard – View – User Login Metrics

Dashboard – View – Password Reset Metrics

A second approach to using the Base pattern with Dashboard stories is around actions performed in conjunction with the Dashboard. For example, the need to export the dashboard to Excel could be decomposed into a separate story.

Decomposition Guidelines

Based upon the complexity of a Dashboard, it may need to be decomposed. Erring on the side of more detail, we prefer to decompose Dashboard and Dashboard-like stories into separate stories for each sub-section and action.

Additional decomposition may be warranted if complex calculations are involved for a specific dashboard value. For example, if a KPI field related to financials involves an average of several values over a rolling time period, divided by several additional calculated values, the calculation may be suitable for further decomposition.

Workflows

Workflows are generally identified by using the “Process” verb within the backlog item title preceded by the noun. Sample backlog items to identify an application workflow would be “Application Process – State Requirements”, “Application Process – Company Requirements”. In creating workflow items, it is important to separate the actual process into its own base user story. So, the application workflow base story title would be: “Application Process – Workflow Order” where the details would specify in what order the subsequent backlog items would be ordered. Thus the overall backlog items in the previous examples would be structured in this order (below):

Application Process – Workflow Order

Application Process – State Requirements

Application Process – County Requirements

Thus, developer(s) can work on each item independently but then can formulate the correct business process order by looking to the base user story.

Base Pattern Usage

As described above, the base pattern is a starting point, specifying the workflow order. When first grooming, it may be important to gather the high-level steps of the work flow. As the details are fleshed out, additional stories can be created from the base story detailing the workflow step.

Decomposition Guidelines

Workflow stories are similar to Management Stories because each workflow step typically requires additional data to be specified, as a result, the same guideline apply – decompose complex validations and ancillary actions that can be performed from each workflow step.

Reporting

Reporting user stories is best to organize by name and within each user story, you identify the fields that are required to populate the report. An additional consideration is to identify the fields that would need to be sortable. Your backlog items, when it comes to reporting, may look like this:

Report – Pending Applications – View

Report – Pending Applications – Print to PDF

Within the first backlog item, your fields may be the following: First Name | Last Name | Date Created | Last Modified Date | Application Status

Where First Name, Last Name, Date Created, and Last Modified are filtered columns.

Base Pattern Usage

Similar to Dashboard stories, Report stories are typically decomposed by functional report areas, based upon complexity and or data relationships. For example, large multi-page and purpose reports may begin with a base story describing the overall sub-sections of the report. As the analysis continues and report sub-sections evolve, decomposed stories can be built for these sub-sections.

Decomposition Guidelines

As noted above, Report stories parallel Dashboard stories. As such, actions performed in relation to a report are generally decomposed into a separate story. For example, printing a report to a PDF, exporting to Excel, or automatically generating a report and saving to SharePoint are typically broken into separate stories built off of the base story.

Calculations

When it comes to making user stories that are designed to use a calculation of some form (or display of a complex number/value that is displayed on a view), it is best to break the user story into a base story, plus the parts that make up the calculation if the calculation is complex (meaning there are multiple business rules to process). If you can break down the calculation into smaller parts, then testing efforts will be much easier prior to testing the overall calculation. So, your backlog items may look like this on a complex calculation:

Tax Rate – Calculate

Tax Rate – Calculate – Business Rule 1

Tax Rate – Calculate – Business Rule 2

Tax Rate – Calculate – Business Rule 3

The base story would then be the combination of business rules 1 through 3, but because you broke them out into individual stories, you can test each business rule to ensure that is working properly making any problems in the programming visible earlier.

Base Pattern Usage

Calculation stories are an excellent example of the base pattern usage. The more complex and multi-step the calculation, the more a base pattern can be built upon. In these stories, we typically have a base story that holds a general calculation, with separate sub-calculation stories.

Decomposition Guidelines

Calculation stories are just like workflow stories; however, they differ in the reason why they are decomposed. Workflow stories are decomposed to understand the clear workflow steps. Calculation stories are decomposed to ease validation and testing.

When decomposing calculation stories, it is important to record specific test case criteria (inputs and outputs) for a particular calculation step. When writing this test criteria, provide sample values that account for normal data cases, and edge data cases.

Action/Activity (Misc. Items go here that builds on other base case stories)

In all previous story categories, we have discussed these action/activity-based stories but did not specifically call them out. An action/activity-based story typically builds upon a base pattern story. For example, emailing a list of user builds off of the base “User Management – View” story. The additional action is “Email List”, and is added to the base case to get two stories:

User Management – View

User Management – View – Email List

Action/Activity stories are typically in the form of verb-noun, specifically describing an action a user of the system takes.

Validation Stories

We have previously described validation stories in the context of Management stories; however, validation stories are a type of Action/Activity story that enforces a constraint on any type of data entry or workflow step. Essentially, any place where additional (and potentially complex) validation logic that prevents a user from continuing down the “happy path” is a candidate for a validation story.

Validation stories are always based off of (or triggered from) an existing story. This story is considered the base story for the validation and should be titled accordingly ([Base Story] – Validate). For example, validating a number format for updating a User would be written as “User Management – Update – Validate Number Format”.

Exception Stories

Similar to Validation stories, Exception stories act as a modifier to a base story. We use Exception stories when the base story describes the “happy path”, and we need to describe complex logic or processes. Exception stories can happy anywhere and can modify any other type of story. They are denoted with exception-like language, such as “Except”, “Unless”, “Only”, etc.