How to write a good user story for cleaner code

What makes a good user story

In their simplest form, user stories are meant to express the purpose of the story for the end user. The user story description should answer three fundamental questions:

• Who is it for?
• What is it?
• Why is it needed?

But these aren't the only integral elements on how to write a user story. It should also include elements on detailed acceptance criteria or minimum standards. Development teams that write generalized stories will often forget detailed acceptance criteria, and, in turn, will cause significant rework and team churn.

For our example on how to write a user story, we'll use an outline/checklist approach. While this is an Agile process, development teams don't need to focus on adhering to a strict format. Instead, use the pieces that work for your team and change what your team doesn't need to improve your results.

Instead of writing detailed, strict phrases in your user story, take a more relaxed approach to the verbiage. It's often just as effective at communicating the user story's intent. A more relaxed phrasing is often just as effective at communicating the overall intent of a user story.

One method is to write the user story description, have a design discussion with members of the team and then fill out the acceptance criteria and other details necessary to develop and test the feature.

An example user story

User story formats aren't set in stone. They just need to work for the development team. A good user story needs to address the three major questions: Who is it for? What is it? And why is it needed? Whether you use a paragraph, outline or checklist, here are some subheadings that every user story should include to serve that purpose:

Description or objective.  This is a generalized statement that defines the objective or reason for the feature or changes and includes the following parts:

• What is the feature's purpose?
• Why is this feature needed?
• Whose need does this feature satisfy?

Persona or user description. Who is going to use this feature or change? For example, for a team that develops medical support applications, perhaps the user story is written to provide a necessary function for a patient or a medical provider. Both users have distinct -- and most importantly, very different -- needs when they use this application. It's important to define at this early stage exactly who the end user will be.

Here's where we have a fork in the road on the how to write a good user story discussion. Many Agile enthusiasts don't believe in detailed descriptions in the user story. But it's in your best interest to add specific details -- such as any technical concerns and acceptance criteria -- to your user story for the best result.

Technical details. The technical subsection describes back-end concerns that need to be considered during the coding and testing phases. This may include data definitions, API information or any other back-end items that play an integral role on how the desired feature should function. Don't forget to add information on known integration points that may affect the feature.

User workflow.  Always keep the end user in mind. In the user workflow section, development teams should incorporate design discussion elements and add specific details of the anticipated user workflow, so they aren't missed during the design phase.

Let's revisit our medical support application example. If we want to add a feature to an application for a patient to record medication doses and order refills, the user story needs to outline the expected workflow. For example:

• Patients fill out the form to sign up for the Medication Management Program through their medical provider.
• Patient receives the Consent form, signs it and returns it electronically.
• The Medication Management Program reviews the patient and accepts or denies their participation.
  • If accepted, the patient receives a welcome email or letter and call from a Patient Program Manager.
    • The patient receives their initial fulfillment of the medication.
    • The patient records dose intake for 3 months.
    • The patient reviews their medical records for accuracy. They check appointments they’ve attended and any results from those appointments.
  • If denied, the patient receives an email or letter indicating they are ineligible for the program.
  • Once the patient reaches the last 30 days of the three-month program, they automatically receive a refill.
  • The refill is sent Second Day air and requires the patient's signature.
  • The refill includes a patient-specific barcode.
    • The patient receives their refill and uploads the barcode.
    • The patient continues to track dose intake for the next 3 months.
    • The patient reviews their medical record for accuracy.
  • The cycle repeats so long as the patient remains active in the Medication Management Program.

When you add details to the user workflow, it ensures the designed code and testing efforts verify the workflow items are met. In other words, when the user receives your code release, they can perform the user workflow steps as expected.

Acceptance criteria and minimum standards. Every end user or customer defines minimum functions they expect the feature to have.  Development teams can save time by incorporating these standards into each story. This can technically happen at any time, but, at the very least, the acceptance criteria should be incorporated before actual development starts.

Why a good user story is important

It's better to have too many details in a user story than not enough. A lack of detail can make your team work harder just to figure out what the eventual customer hopes the feature will do. Details like the end user description and technical elements aren't specifically required in a user story, but they can save time and effort down the road.

Remember that user stories are agile; you can change them to meet your needs. If your application doesn't have integrated connectivity, then the user story doesn't need the technical details section. The same can be said about the user workflow section. What's essential is clear, concise and specific wording that answers the most basic questions.