On writing requirements

How do you write good requirements? What’s your process for writing them? These are often the first question people new to PM ask. And rightly so! A PM’s primary job is to figure out what to build and then write a set of clear instructions for the engineering team to actually build it.

The ability to write complete and clear requirement cannot be overstated. It gives you more credibility with the engineers, reduces preventable rework due to missed requirement, and most importantly, frees up your time to focus on future product releases.

There are lots of instructions on how to write a typical user stories in the Agile environment. However, I found that they either stay super high level, or give examples that are overly simplistic and doesn’t take into account the complexities of real world development.

How I write my user stories

Over the years, I have developed my own template that seems to work well. Hopefully, this will be a helpful guide for you when writing your own. I have attached actual samples of requirements that I wrote. It’s on an email subscription feature I worked on in the past.

Sample requirement

Template

Context

This section is the section that talks about why this feature exists (i.e. the problem this feature/story is trying to solve). I actually put a decent amount of time into this section because

1. developers are smart people. If you give them a clear reason behind why they are building this, they can make much better architectural design decisions.
2. In case that I missed something in the requirement, the developers will more likely to bring it up with me because they have a much better understanding of what I am trying to achieve.

User Story

This is your typical user story phrase. “As a <type of user>, I want <some goal> so that <some reason>.”

Design/Mockups/Flowcharts

This section usually house the links to the design, mockups, and flowcharts associated with the feature. Basically whatever material to help better communicate what the feature is suppose to do.

Detailed User Story

This is where I get into the weeds. It explains all the major interactions associated with the feature. If people have taken basic programming courses in college, it kind of reads like a programming using english. There are 3 basic components that I outline in this section:

• User state: declares the different possible state for the user (i.e. signed-in? admin vs regular user, etc.)
• Display: describe the different variations that should be displayed based on different user states
• Behavior: describe what interaction is possible on the page and what the expected response is after the user input

Reference

I include all other reference that I think are useful in this section. They typically include links to assets the developer need to use and/or documentation to 3rd party system they need to connect to.

There you have it.

This is the basic template I use to draft my requirement. Hope this was helpful. If you have any thoughts/comments, feel free to leave it in the comment section below 🙂