Overview

One of the most important aspects of successful projects is clear and unambiguous communication. Stakeholders and developers must have a univocal understanding of what is being built.

We employ a process that requires us to split requirements into manageable units of work. We typically place these units into one of three categories: user stories, tasks, and bug reports.

User stories

User stories are simple descriptions of requirements told from the perspective of the entity that desires the outcome. They can take many shapes, but should answer the "who", "what", and "why". A specific format should be followed to remind stakeholders to focus on outcomes and value delivered. The following format is commonly used:

As a(n) <type of user>, I can <some requirement>[, so that <some reason>].

Example:

As a *user* I can log in so that I can access my dashboard

Or:

As an *adminstrator* I can create user accounts so that I can grant
users access to the system.

A good story should be clearly defined, actionable, testable, independent, and small enough to be completed in a couple of days at the most. Having that said, many stories start as coarse-grained general descriptions and then evolve into what we consider good stories.

Users

As the name suggests, user stories are told from the perspective of a user. One of the first actions in any project should be to identify the different users of the product.

Coarse-grained stories

A project typically starts with a few coarse-grained stories. They are rough and very broad and allow the stakeholders to start thinking about, discussing, and prioritizing requirements without committing to details. These stories cannot generally be acted upon and serve as placeholders for more detailed stories.

Example:

As a *gamer* I can find games.

Splitting stories

There's a balance to writing user stories. On the one hand you want them to be small in terms of workload and on the other you want them to be detailed enough to be clear. And you can achieve both! By splitting a story into two or more smaller stories you can reduce the amount of work needed to realize the story while adding more details by describing how the stories diverge.

We could, if we continue with the example above, split our course-grained story (the one about finding games) into the following two stories:

As a *gamer* I can browse games so that I can explore the catalog.

And:

As a *gamer* I can search for games so that I can find a specific game.

Acceptance criteria

Acceptance criteria are a set of conditions the implementation of a story must satisfy in order to be accepted. The criteria can be functional (e.g. particular feature or technical condition) or non-functional (e.g. performance or robustness).

The acceptance criteria should be kept simple and without ambiguity describe the condition to be met. Whether a criterion is satisfied or not should always be binary.

Example of criteria:

As a *gamer* I can browse games so that I can explore the catalog.

- The list is paginated and at most 100 games are displayed
- Games can be sorted alphabetically
- Games can be sorted chronologically

The criteria can also be used when splitting user stories if a criterion does not share the priority of other criteria in the story. The story above can be split into two stories with different priorities:

As a *gamer* I can browse games so that I can explore the catalog.

- The list is paginated and at most 100 games are displayed

And -- as it might not add value in the beginning of the project -- we can de-prioritize the following story:

As a *gamer* I can sort games when browsing.

- Games can be sorted alphabetically
- Games can be sorted chronologically

Tasks

Not everything in a project pertains to its users directly. Some requirements are hard -- or at least meaningless -- to describe as user stories. We call these requirements Tasks.

A task is something that does not on it's own deliver value to the project. Things like setting up servers, creating domain records, and writing or refactoring code are often created as tasks.

Tasks can be a part of a user story or exist as independent entities in the project. The important thing is that they describe discrete pieces of work written in a language the team understands.

Example of tasks embedded in a user story:

As a *gamer* I can browse games so that I can explore the catalog.

- The list is paginated and at most 100 games are displayed
- Games can be sorted alphabetically
- Games can be sorted chronologically

[ ] Create new react component
[ ] Add a game serializer
[ ] Add viewset to retrieve games
[ ] Add pagination settings to the viewset
[ ] Add a filter backend to handle sorting

Example of a stand-alone task:

Go through all stylesheets and remove any unused rule-sets.

Bug reports

We also differentiate between user stories and bugs. Bug reports require a different context. Having that said, bug reports can be converted into stories if it is in essence a feature request or caused by a shortcoming of the initial story.

Bug reports should contain as much context as needed to adequately describe what happened. We use the following format:

• Summary: (mandatory) A brief description of the bug or problem. Try to strike a good balance between brevity and information.
• Steps to reproduce: (mandatory) Description of the steps that were taken when the bug was encountered. If you cannot reproduce the bug it is important that you mention that.
• Expected outcome: (mandatory) What you expected to see.
• Actual outcome: (mandatory) What you saw instead.
• Problem: (optional) Describe why the outcome is a problem.
• Severity: (optional) Severity level of the bug. One of: critical, major, minor, and trivial.
• Context: (optional) Any additional information that can help the person assigned to the bug locate and fix it (e.g. screenshots, environment, URL etc).

Example:

Summary:
Cannot create account with long email address

Steps to reproduce:
Go to the create account page. Enter an email address containing
a total of 50 characters or more. Click "Create account"

Expected outcome:
An account is created with the email provided.

Actual outcome:
An error message is displayed telling me the email is too long.

Problem:
Users with long email addresses cannot create accounts.

Context:
I tried in latest versions of Firefox and Chrome.

[Screenshot of error message]