Project management best practices: Stories

Posted Over 8 years ago. Visible to the public. Repeats.

We organize our daily work with stories in Pivotal Tracker.

Story format

A good story needs to be precise. It should be very clear what is part of a story, and what is not. If there are different expectations between the person who writes and who implements a story, there will be rejects.

To this end, we use a consistent format for stories that looks like this:

Story: Autocomplete

As a journalist, I want to have an autocomplete in the search bar, to have a more efficient way to find articles.

Acceptance criteria

- When I enter 2 letters into the search bar on the desktop homepage, I get a popup with autocomplete suggestions.
- The suggestions are as determined by ElasticSearch.
- When I keep typing, the suggestions change.
- When I erase my query, the popup disappears.
- The popup contains a maximum of 10 suggestions.
- When I click outside the popup, it disappears.
- If I click on a suggestion, I am taken to the search page as if I had entered the suggestion.
- The letters entered are highlighted in the suggestions.
- Design is here: <link>


- The autocomplete on the mobile homepage is not part of this story.
- At some time we will also show tags in the suggestion list.

The story consists of a short introduction sentence, a list of acceptance criteria and (optionally) some additional notes.

The introduction sentence should include the role of the user, what the user wants and why.

The acceptance criteria are very verbose to the point of being too obvious. Everything that needs to happen is a bullet point. As a developer you can go through the list and make sure you didn't forget anything. You can be assured that nothing else is expected of you.

The notes can give you hints to future planned changes that you can consider when writing your code. They are just there to give you context.

Who writes the story

To write a story, one needs to know exactly what the client requires. Only the product owner or product manager can do that.

One also has to know the application, in order to foresee edge cases and difficulties that non-developers might forget.

If the project owner is also a developer, she can write the story on her own. If the project manager is not a developer, she can prepare it, but needs to discuss it with a (lead) developer before it is ready.

The backlog

Every story should begin its life in the icebox and only be moved to the backlog if it is ready to be worked on. The backlog should be a prioritized list of stories based on their urgency.


We use estimates on stories to give developer a rough idea of how long it should take to implement a story. Otherwise it might happen that a developer does something much too complicated, because he wasn't aware of some shortcut, or some feature that is already implemented.

We don't want very exact estimates, because they can easily start to frustrate a developer, if the story turns out to be more complicated than anticipated.

We suggest a 0,1,2,3 point scale, with the following meaning:

  • 0 points: <= 1h
  • 1 points: <= half a day
  • 2 points: <= a day
  • 3 points: > a day

If a story takes longer than 2-3 days, you need to split it.

Tobias Kraze
Last edit
3 months ago
Paul Demel
Source code in this card is licensed under the MIT License.
Posted by Tobias Kraze to makandra dev (2015-09-11 14:34)