Metal Toad Templates Part 3: Our User Story Template

Following up on part 2 introducing our agile burndown spreadsheet template, part 3 focuses on our User Story Template, another document rooted in Agile concepts that we apply to many projects regardless of their methodology. This one was created by Tom Martin Mat and Jordan as they worked through a huge number of user stories for a project a number of months back.

This template is very simple, but has served us well during project discoveries to introduce the concept of user stories to clients while documenting their project's needs. It includes three levels of structure: archetypes (or personas), features for those archetypes, and scenarios for the features. I'll get a little further into each below.

Personas and/or Archetypes

Depending on the needs of the project and our approach with the client, we'll either create stories around personas, archetypes, or potentially both. It's important to note the difference between a persona and an archetype, as "Developing Archetypes" does a good job of calling out.

An Archetype is a model for a category of user. It defines behavior patterns, thoughts, and needs across a specific type of user relevant to your project. A persona is a specific fictitious individual, usually given a name, who has specific traits and attributes assigned. A persona could be created that fits within an archetype, which is a great way to break things down. Our experience has been that archetypes are most useful to identify high-level business requirements, while personas are beneficial for functionality walkthroughs and test cases on a more granular basis. As such, we'll often sort features by archetype, and we'll use personas to walk through individual scenarios within a feature.

Features and Scenarios

When it comes to features, we use Gherkin-style language, which basically reflects the standard terminology of a user story from Agile. Gherkin can sound a bit robotic, but I'll get to some big plusses from that format in a bit. Features start with "in order to..." which states the basic business goal of the feature, followed by "As a..." which identifies the archetype/persona, and finally "I want to..." which should be a high-level description of the intended functionality.

Within each feature, we'll write anywhere between one and several dozen scenarios. These scenarios get much more into the weeds of a specific feature, and should cover as many common use cases regarding a feature as possible. Again, they follow Gherkin-style language of Given-When-Then. Once we've written out and reviewed scenarios with clients to make sure we've covered the important aspects of a feature, things can get really fun! We've invested fairly heavily into familiarizing ourselves with behavior-driven and test-driven development, and Behat is one of our tools of choice. Note that Behat actually parses Gherkin language. That means that we can take our features and scenarios and convert them almost directly into Behat tests! If we don't end up doing Behat on a project, the scenario language still gives our QA team a clear idea of the scenarios they should be testing against.

This document and the whole process around it can have some major wins on a project. If all goes well, we create a document that mines the brains of our clients for valuable features to build and scenarios to define the feature, and it greatly aids our QA process by giving us a list of scenarios to test against for pass/fail validation, which we can then report back to clients.

Check out the template (which includes some example features and scenarios) and feel free to make a copy and repurpose for your own use!