Over a million developers have joined DZone.

INVEST in User Stories

DZone 's Guide to

INVEST in User Stories

Like the SOLID and the GRASP acronyms for the famous object-oriented design principles, there is also an acronym that describes the properties of a good user story: INVEST.

· Agile Zone ·
Free Resource

User stories are the basic units of work for Agile methodologies. They describe features to implement in a system and are one of the primary artifact generated before coding a prototype.

Stories are usually written on a 3"x5" card in the format:

As a <User Role>, I want to <Action> so that <Goal>.

Writing a simple phrase seems very simple, but the specification activity behind it is not so trivial. The example of this article is that of a story about adding a Popular articles widget to a content management system (or a similar application).

Like the SOLID and the acronyms for the famous object-oriented design principles we can keep in mind, there is also an acronym that describes the properties of a good user story: INVEST.


Independency between stories is fundamental for being able to prioritize, add and remove stories from a release or an iteration plan as single units. Stories should be atomic, so that can be started and finished in isolation from other ones (like a database transaction).

Usually this completeness is achieved by defining a story as a vertical slice of an application, a feature that encompasses the database layer, the domain model and the user interface at the same time.

In our example, our Popular article widget should not depend on other stories like completing a high-level Api that widgets can call to retrieve data: this task would not even be a story in my opinion. Ideally, the Api construction would be sliced up in the various widget stories, with each widget forcing to add the part of the Api that it calls (for our widget, may be a getArticlesOrderedByViews() method.) The beauty of this approach is that we'll never include in the Api something that no other component actually requires.


The original definition of story is that of a reminder to have a discussion with the customer/domain expert/customer proxy about this feature. A 20-page specification document that specifies everything is not a story.

The story has to capture the essence of that has to be done, by whom, and why it has to be done. Everything that is not needed for prioritization and scheduling of iterations is not required initially: it would be premature and would add weight to the story, making us less likely to drop it without fears when it is the case, due to the work already done on it.

How many articles should our widget display? Is there a threshold of minimum views to be achieved by an article before being featured there? The view should span over a month, a year, or on an all-time basis? Are these options configurable? The story definition is not the time for capturing these details, since once you have a grasp of the general level of complexity you can already estimate it. If more features pop up you can negotiate what should be included, while creating other stories to discuss later, once the base feature is in place.


What this story is for? It is really needed? Moreover, it is valuable to the customer or customer proxy we are dealing with, or only to the programmers?

Adding fields to a database table without showing them is not a story, since it does not have value for the customer in itself and maybe a worthless task. The modifications needed to the database must be included in a valuable story (or many of them).

In the Popular articles widget example, we are showing the user the most viewed articles of the month, so that he can jump to the content that it would probably interest him with a single click. This is real added value, while preparing the internal Api was not.


As humans, we are not good at dealing with a range of values (estimation values) that span more than a magnitude. Typically stories are estimated in points or ideal hours, where the value range along the start of the Fibonacci sequence (each term is the sum of the two preceding it):

1 2 3 5 8 13 [21 34]

Sometimes a story comes up that would have a 0.5 or a 100 length. When a story is too big, you should divide it into simpler stories, or into a spike story of exploration with a fixed time limit plus another one to estimate after the spike.

Analogously, when a story is too short, you may bundle it up with other small stories or include it in one of the other ones. Not only the size of a story influences estimation: also the understanding of the developers on what is needed to complete the story. This is why the team in its entirety should estimate in a single seat.

Our widget is probably simple to estimate, but we must ask the customer enough information to make a guess, without descending too much into details. For example, we must know if the must access external data sources other then the application's own data, since that would probably influence the technologies the developers have to use.


The more stories are near to start the development phase, the more they should be kept small, even by breaking up them in independent pieces. The 'Small' trait is related to the Estimable one: smaller stories are easy to manage, estimate and compose.

In fact, it is much more likely for a story to be too big then too small. Our widget is small enough to be completed in an iteration, in this case even in a day.


Acceptance tests are usually written on the back of the card (when using a physical system). The tests are written in a natural language definition, since code wouldn't fit on a card.

If a story isn't testable, rethink it, or you'll never have a definition of Done on its development. Done is when all the acceptance tests pass (hopefully automated ones).

Our widget can be tested by populating an instance of the application with a set of fake articles, each with a set of views stored along it. Then we can access the widget through an acceptance test on the user interface, or instance it independently, and verify the correct articles are selected, ordered, and displayed as expected.


After revising the INVEST principles, we have our final version of the story:

As a User, I want to see a Popular Articles widget on each page, so that I can jump immediately to the more interesting articles from anywhere.
agile ,css ,user stories ,estimation ,negotiation ,invest

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}