Product Planning

Hero image for Product Planning

For managing application development, we are using Pivotal Tracker (abbreviated PT), an Agile-based project management tool.

With time and practice, we have settled on a very particular and, in our case, efficient workflow with PT. Hereafter is the documented workflow.

You should refer to this documentation if you:

  • Need to scope a project,
  • Need help understanding a new project.

Nomenclature

To break down a large project into manageable -and meaningful- blocks, we are relying on Epics and a Label Nomenclature for user stories. These two components are tightly linked together as labels are used to associate user stories to epics.

There are four types of epics defined as follows:

  1. Module
  2. Feature
  3. Release
  4. Standard

Module Epic

Definition

  • Modules represents the main components of an application.
  • Modules are the smallest denominator to which the app can be reduced to. It often corresponds to navigational sections (i.e. each navigation menu item points to a component of the app).
  • A module contains several feature epics.
  • There are recurrent modules such as User Account and User Profile (those are, by default, in the project template).

Nomenclature

  • Epic Naming: Module - Module Name (Markdown: **Module - Module Name** as Module should be in bold)
  • Label Naming: #the-module-name

Feature Epic

Definition

  • A feature is a coherent and standalone group of user stories that defines a functionality in the application.

Nomenclature

  • Epic Naming: Feature - Feature Name (Markdown: **Feature** - Feature Name as Feature should be in italic)
  • Label Naming: $the-feature-name

Release Epic

Definition

  • A release can either be a version or a milestone.
  • A release contains several user stories. An entire feature epic can be delivered in one release, or throughout multiple releases.

Nomenclature

  • Epic Naming: Release - 0.0.1
  • Label Naming: @0.0.1

Standard Epic

These epics are recurrent in every project. They do not relate to a particular feature of the app, but to the app itself, in its entirety.

APPLICATION

Definition

  • The Application epic regroups all user stories that have an application-wide impact.
  • Often corresponds - but not limited to - application setup tasks.
  • Often corresponds to user stories of type chore as these tasks do not deliver a feature but are necessary for the implementation of features (e.g. implementing error pages).

Nomenclature

  • Epic Naming: APPLICATION (Markdown: **APPLICATION** as it should be in bold)
  • Label Naming: !application

QA

Definition

  • The QA epic regroups all user stories resulting from internal and external feedback, and bug reports.
  • User stories in this epic will initially not have any module epic attached to them. This epic serves as a bucket for all QA issues. Eventually, each story will be labeled with the corresponding module, feature and release epics.

Nomenclature

  • Epic Naming: QA (Markdown: **QA** as it should be in bold)
  • Label Naming: !qa

TESTS

Definition

  • The TESTS epic regroups all user stories related to new or existing application tests.

Nomenclature

  • Epic Naming: TESTS (Markdown: **TESTS** as it should be in bold)
  • Label Naming: !tests

Template

To get a quick start for new products, a project template is available in PT.

You can get started with the template in three steps:

  1. Export the template (make sure to check all the boxes when exporting),
  2. Create a new project in PT,
  3. Import the template in the newly created project.

The following screencast illustrates the export / import process.

PT Project Template

User Stories

Writing a (Good) Story

Writing a good story is important. The difference between a good and a bad story can be the difference between good and bad implementation.

A well-written story will give the developers more independence while ensuring an implementation that follows the project specs and design.

There are five parts to a story:

  • The title,
  • The description,
  • The tasks,
  • The comments,
  • The labels.

In addition to that, a story also has a type:

  • Feature: a feature of the project that brings value to the end-user.
  • Bug: an issue, unexpected behavior, or broken feature of the app. Bugs are often identified and reported during the QA phase and, consequently, often labeled !qa (see more details).
  • Chore: a task that does not bring direct value to the end-user, but that is necessary to the project development.
  • Release: a milestone in the development process, usually meaning the release of a new version (in which case you must attach the release story to a release epic).

The Title

A user story is written from the perspective of the user. The story should describe an action that the user can undertake.

For instance, a user story defining the user email sign-in into an application should go like this:

As a user, I can sign-in using my email and password

The user, however, is not always a “user” per se. In an application that has an administrative area, the user can be an administrator.

To re-use the example above, a user story defining the admin sign-in into the admin panel should go like this:

As an admin, I can sign-in into my admin area using my username and password

The Description

NOTE: In Pivotal Tracker, all markdown titles are displayed the same, regardless of hierarchy. Using one single # for titles is enough.

The story description is, mostly, used for three purposes:

  • Giving context: why this story/feature? What’s the general mechanics of it? Example:

When signing-in, the standard users (those with the role user) will be redirected to their user profile. The admin users (those with the role admin), will be redirected to the admin dashboard.

  • Adding details: if the feature involves something that isn’t obvious or intuitive, it must be explicitly titled and detailed (titles must be formatted using one #). Example:

Greeting the User

After redirecting the user (standard users only, with the role user) to his user profile, display a greeting message at the top of the screen that reads: “Howdy, {user}. It is nice seeing you again so soon!”

  • Leaving general notes: for when something else needs to be said but doesn’t fall within one of the standard categories detailed above. Notes are usually left at the end of the description and must begin with Note: (markdown **Note:**).

Front-End Specificities

More often than not, front-end stories will involve design implementation.

While this is not possible during the spec’ing phase, once the design is ready, all relevant stories must contain a link to the appropriate design. Add the title **Design** and simply paste a link the design file (e.g. Invision).

Back-End Specificities

Back-end stories, when they relate to CRUD operations, must contain a Fields section and list the relevant fields for the story.

The back-end story for a sign-in feature, for instance, could have the following fields:

  • Username *
  • Password *
  • Password (repeat) *
  • Birthday
  • Terms and conditions *

The * sign identifies fields that are mandatory.

Statuses

User stories go through 6 development states:

  • Unstarted (default): No work has been done yet.
  • Started: The assigned team member started working on the task. Consequently:
    • A new branch has been checked out from the development branch,
    • All commits related to this story will be pushed to the new branch,
    • Optionally, a work in progress pull request can be opened for an early review. It must be suffixed [WIP].
  • Finished: The assigned team member finished working on the task. Consequently:
    • A pull request for this branch has been opened OR, if a work in progress pull request had been opened already, the suffix [WIP] has been removed from the pull request title,
    • No new commits will be pushed to this branch,
    • Code reviewers will review the pull request and either approve or reject it. In the case of code reviews requiring the push of new commits, the story’s status must imperatively be reverted to Started when the assigned team member starts working on it again. Doing so is critical. There should not be more than 1 or 2 Started stories(s) at a time for each team member. This helps in providing greater visibility on what the current tasks at hand are.
  • Delivered: The assigned team member finished working on the task and a code review has been completed and accepted. Consequently:
    • The branch has been merged into the destination branch, as defined in the pull request (development branch by default),
    • The branch for this story has been deleted,
    • If continuous delivery is set up, the destination branch will be built and deployed (web) / compiled (mobile) automatically to the staging / beta environment,
    • Team leads / PM must review the changes on the staging / beta environment.
  • Accepted: The assigned team lead / PM reviewed positively the delivered story. This story is now fully completed.
  • Rejected: The assigned team lead / PM reviewed negatively the delivered story. Additional work is required. In this case, the assigned team member will start working on the story again, repeating the full cycle, from Started to Finished, to Delivered, until it gets Accepted.

Acceptance Criteria

In Pivotal Tracker, we use the tasks to list the acceptance criteria.

Acceptance criteria will help:

  • Implement the feature as accurately as possible,
  • Test the feature implemented,
  • Decide if a delivered feature is accepted (by the PM or team lead) or not.

After implementing the feature, developers must check the tasks before delivering the story. An unchecked task is considered not done and may not be reviewed by the PM/team lead.

For a sign-in feature, the front-end acceptance criteria could be:

  • Disable sign-in button by default
  • Validate email format (to avoid typos)
  • Enable sign-in button when email and password fields have been filled
  • Show error message above sign-in form if sign-in failed

The Comments

The comments are most useful during the spec’ing phase - to discuss and refine the stories -, and after feature delivery - to detail rejection reasons in particular -.

There is no hard rule on comments use or formatting. One general practice, though, is to tag other users when referencing them (reminder: tagging a user is done by typing the @ sign, immediately followed by the username. PT has an autocomplete feature).

Front-End vs. Back-End

Generally speaking, and especially during the spec’ing phase (as opposed to the development phase), most of the stories will go by pairs.

A pair will define the front-end and the back-end components of a feature (labeled frontend and backend respectively).

The main reasons for separating front-end and back-end are:

  • Breaking down a feature in targeted tasks (not all devs in a team have the same skill-set),
  • Allowing for asynchronous front-end and back-end implementation,
  • Leaving back-end developers and designers independent from each-other.

For example, defining a sign-in feature would be done in two stories.

Front-End

As a user, I can sign-in using my email and password

Back-End

API As a user, I can sign-in using my email and password

The two titles are almost identical. The only difference between them is the addition of the API prefix for the backend story (the prefix must be bolded and capitalized, markdown **API**).

Attachments

Attachments can be very useful. For front-end implementation, bug reports or rejection comments, a screenshot can be worth a thousand words.

There is no rule on how to edit a screenshot, but it is common practice in the team to attach one for pointing at specific elements when integrating UI elements or reporting a bug.

Note: For Mac, Skitch is a simple and powerful tool for taking and editing screenshots.

The Full Sign-In Example

In this section, we’ve seen a sign-in feature as an example for almost all the sub-sections. Now, here is the complete example of a sign-in feature spec’d down.

Note that the front-end story is on the left, and the back-end one is on the right. Sometimes the front-end story will have more details, sometimes the backend story will.

Example Story

Story Estimation

Once a story has all the required meta-data (title, description, acceptance criteria), it needs to be estimated by the development squad.

The estimation can be done either by a single developer or by the whole development squad. We usually do not follow any formal methodology such as Planning Poker but favor open communication. We also accept and actually embrace that estimation can be biased based on who will estimate. As long as the individual or squad who made the estimation is also the one who will execute the work, the estimation will likely be correct and will represent the actual velocity of the individual and the development team over time.

Scale

We use the Fibonacci-based scale 0, 1, 2, 3, 5 and 8 to estimate feature stories.

As a generally accepted agile pattern, bug and chore stories are NOT assigned any point as these stories cannot be properly estimated.

Estimation Guidelines

When assigning points to a user story, we follow the multi-faceted guideline hereafter:

  • 0 point: no complexity, no unknowns. The effort required is usually less than an hour, e.g. change of text or image.
  • 1 point: no complexity, no unknowns. The effort required is usually between a couple of hours and one day.
  • 2 points: no complexity (as-in “it’s something I have done before”) but it takes more time to implement than a two-point story. So the effort required is usually around 1-2 days.
  • 3 points: medium complexity due to having some unknowns and needs for research. So developers probably know how to do 50% of it only. The effort required is usually between 2-3 days.
  • 5 points: high complexity due to having lots of unknowns because either it requires lots of research or because developers have never done it before. The effort required is usually between 3-5 days
  • 8 points: indicative that the story is too complex or large, thus needs to be re-worked and broken down into smaller stories