User Story Titles on a Whiteboard

in Research

Naming Guide for Task, Bug & User Story Titles

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

Task titles have a direct bearing on you and your team’s ability to understand the work that needs to be done and your teams’ 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 tasks’ titles (or your issue summaries if you’re using JIRA). You’re often under pressure with a deadline or your mind is deep in another problem to spend the time to think hard about a task title. You just want to get it in the system and move on.

Task Title Problems

The problem is a poorly written task title 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 than 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 hypothesis about what the best naming conventions for different types of tasks are. Over time we’ll validate these titles with real data in ways you didn’t think possible or necessary (I get over-excited about data-driven decisions). The types of tasks listed below are based on the Issue Types found in JIRA. Here is our hypothesis:

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>

The list is meant to eventually be comprehensive so please share your thoughts. Over the coming weeks and months we will expand upon these task, bug and user story titles by supporting them with data.


Also published on Medium.

Write a Comment

Comment