Naming Guide for Task, Bug, and User Story Titles

Naming a task, bug or user story title seems like a small or inconsequential part of daily life on software projects, but task titles have more impact than you might think. I’m on a quest to use every little detail and data point possible to evolve the way software projects run—and titles are my current obsession.

Task titles have a direct bearing on your team’s understanding of the work that needs to be done, which influences the team’s ability to do it effectively. 

You probably create a number of tasks each week and only give a passing thought to the format of your task titles (or your issue summaries if you’re using JIRA). You’re probably too under pressure with deadlines or other problems to spend time thinking about a task title, you just want to get it in the system and move on.

This article will outline some of the problems of rushed or ill considered task titles, and offer some easy to follow conventions for keeping your teaming working effectively.   

Task title problems

A poorly written task title will create misunderstandings that can lead to:

1. People doing the wrong thing. This is probably the worst outcome from a poorly written task title, yet it happens all too often. Someone sees the name of the task and immediately begins work. It isn’t until a week or two later (if you’re lucky) that you realise you’ve just lost days of work and built the wrong thing.
2. Inconvenience and lost time. Other people on your team will need to click through to view the details of the task, which adds a few unnecessary extra seconds. This adds up over your life-time, and the course of your team’s project. If the time doesn’t matter then the frustration will.
3. Your task being ignored or neglected. When grooming the backlog and trying to prioritise, people may misunderstand your poorly written task name and just ignore it or leave it (because they think it isn’t worth doing).

The industry standard task naming convention

In order to save software teams from these problems, I’m putting forward a proposed format for the best naming conventions for different types of tasks. The types of tasks listed below are based on the Issue Types found in JIRA.

User story titles

A user story is a behaviour or feature that a solution needs to implement in order to fulfil the needs of a user.

The proposed formats for user story titles are:

1. As <a> <persona/type of user>, I want <something> so that <some reason> (e.g. As Sam Spendsalot, I want to one-click purchase so that I can get my goods as quickly as possible)
2. As a <persona/type of user>, I want <something> (e.g. As a User, I want to create a task)
3. <persona/type of user> <performs action on> <thing> (e.g. User visits home page OR User creates a task)

The format for user story titles is thanks to Microsoft’s MSDN who credit this to Mike Cohn at Mountain Goat Software.

Bug titles

A bug is a problem that impairs a product or service’s functionality.

The proposed formats for bug titles are:

1. <person/type of user> can’t <perform action/get result they should be able to> (e.g. New User can’t view home screen)
2. When <performing some action/event occurs>, the <system feature> doesn’t work
3. When <persona/type of user> <performs some action>, the <system feature> doesn’t work
4. <system feature> doesn’t work
5. <system feature> should <expected behaviour> but doesn’t
6. <system feature> <is not/does not> <expected behaviour>
7. <persona/user type> <gets result> but should <get different result>
8. <quick name>. <one of the formats above> (e.g. “Broken button. New User can’t click the Next button on Step 2 of the Wizard”).

The bug title formats are based on our analysis of close to 5,000 tasks across a few different organisations, projects and teams.

Task titles

A task is an activity that needs to be performed that doesn’t fall into one of the other task types. This is often something the team has to do but doesn’t result in code.

The proposed formats for task titles are:

1. <verb/action> <activity> (e.g. “Perform backup”)
2. <verb/action> <thing> (e.g. “Research new javascript framework”)

These formats are also based on our analysis of raw data.

New feature titles

This type of task is mostly used with services or components that are somewhat removed from the end user, such as API endpoints.

The proposed title formats for new features are:

1. Implement <endpoint> (e.g. Implement POST /api/v1/users)
2. Create endpoint <endpoint> (e.g. Create endpoint POST /api/v1/users)

Improvement titles

Improvement tasks are usually minor changes to functionality.

The proposed title formats for improvements are:

1. <endpoint> > also <additional functionality> (e.g. POST /api/v1/users > also accept date of birth)
2. <component> > also <additional functionality/
3. Make <feature> run faster
4. Improve the performance of <feature/screen/endpoint>
5. Update <feature> <with/to> <update>
6. Rename <feature/text> to <new name>

Summary

You shouldn’t rush the naming of your task—it’s not as insignificant as it might feel. By following some simple principles for titles, your project’s seperate components will be more comprehensible to you and your team. With these simple naming conventions, everyone in your team will be able to quickly understand and then appropriately prioritise your tasks, bugs, user stories, new features, and improvements.

---