On Writing Feature Requirements

Avatar of Geoff Graham
Geoff Graham on

I have been asked to lead product development on a team. This is somewhat of a new journey for me because I’m generally used to calling myself a web designer rather than a product manager or strategist.

The toughest part of this job for me has been organizing my thoughts. I’ve written an executive summary for the product we’re building, done some competitive research and even dusted off my limited MBA education for a SWOT analysis. Oh yeah, now it looks like I know what I’m doing!

Many of us who read CSS-Tricks with any sort of regularity likely have to think strategically to do our jobs, whether it’s in design, development, or both. What I’ve found, however, is that thinking strategically is a whole lot different than acting strategically. Where thinking strategically is an internal process that stays in your head, acting strategically requires careful orchestration and the ability to document internal thoughts in a way that can be shared and understood across a team.

The difference between thinking and acting strategically was never truer to me than when I sat down to write feature requirements for this project. I thought I would share what I’ve learned in my early attempts to write requirements.

Before I get started, I do want to say that there is no shortage of ways to approach feature requirements. What I’m about to share largely borrows bits and pieces that I’ve found crawling the web for answers to my own questions and piecing them together in a way that works for me.

Recognize Your Bias

The first thing I had to learn to accept is that I am biased in how I approach requirements. I am a web designer by trade and, as such, my thinking tends to be on the visual side of things. I can sketch wireframes and produce mockups all day long, but not all people on the team see or think this way.

There is nothing wrong with a bias towards visual thinking, but it’s worth recognizing it and remembering that your documentation will need to make sense to others. In my case, I’ve had a blast sketching layouts and drawing a bunch of squares that represent how users navigate through the product. That’s helped me get my thoughts out of my head so I can start the process of documenting them. Your process might be bulleted lists or diagrams. Use what makes sense to you and know you will need to translate that work for others.

Tell a Story

I have also learned that thinking about features as stories helps a lot.

Think about it: a story has a protagonist (the user) who is finds herself in a situation (the user flow) before reaching an inciting incident (the task to complete) in order to find a resolution (the expected outcome). Who knew Stephen King was a master at writing feature requirements all this time?

My process so far has been to make a list of all the key product features, then tell a story from the perspective of the end user about how they are using each feature. Our team is calling these user stories, and each feature can have as few as a single story and as many as a dozen, depending on the use cases.

User stories are great because they force you to think from a user’s perspective and to focus on expected outcomes. Let’s say we are writing the requirements for Account Creation. Here is how we’ve been framing each user story:

As… I expect that… So that…
[Identify the user] [Describe the task] [Explain the anticipated outcome]

Let’s say we are writing the requirements for Account Creation. Here is how one user story for it might be written:

As… I expect that… So that…
Any new customer I can use my existing Google or Facebook account to sign up I can sign-up faster and manage fewer accounts

I will interject here to say that this exercise requires that you have a darn good understanding of who your users are. Sure, the example above is rather generic because it targets “any new customer” but thinking through who your users are, documenting their personalities and even going so far as to give them names will allow you to be more specific and contextual when writing user stories. MailChimp has a wonderful write-up on their process for creating user personas that was super helpful for me.

Document User Flows

If a user story helps set expectations for a feature requirement, then a user flow provides context for how the user got there and where she ends up after completing the task.

Going back to my personal bias for visual thinking, it makes the most sense to me to see this in a diagram. However, I know not everyone thinks like me, so I have been outlining the required steps a user takes to accomplish the task and using a diagram to illustrate more complex flows.

Here’s how my I might write up a flow for the user story we used earlier for social sign-in in an account creation feature:

User Flow ID Description
UF-1 Customer responds to a call-to-action on the marketing site to create an account
UF-2 Customer chooses to register a new account using a Google or Facebook account on the Account Sign-Up screen
UF-3 Customer selects either Facebook or Google
UF-4 Customer is prompted to authorize the use of their selected account to register an account by verifying her identity
UF-5 Customer either:

  • Denies the authorization and is directed back to the Account Sign-Up screen
  • Approves the authorization and is directed to the User Story 2

Notice how each step is given an ID and each ID can branch off into sub-tasks. The IDs are useful for being able to refer to specific points in the documentation when discussing them with others on the team. This can certainly get messy, which is where a nice diagram can come in handy.

An example of a user flow diagram

Document Requirements

The crazy part in learning how to write requirements is how much forethought is required before you really start getting into the requirements.

Once the feature has been identified, a user story is written, and the flow outlined, I move into the actual requirements, using the same format that was used for user flows.

Again, back to our social sign-in example, some simple requirements might be:

Requirement ID Description
RQ-1 A Google Analytics funnel to measure conversions and drop-offs
RQ-2 OAuth integration
RQ-3 Options for Facebook and Google

You can be as detailed as you need to be. I try to err on the conservative side and write as many as possible, while trying not to be too rigidly defined that it stifles creative license during design and development.

Be Transparent With Assumptions

I’ve learned that every decision I make is wrought with assumptions. It’s hard to be aware of everything, but acknowledging anything you might be taking for granted is important because it provides a window into the decision-making process. Documenting assumptions allows others to understand your logic and provides an opportunity to fuel further discussion.

Let’s document a few assumptions in our running example:

Assumption ID Description
AS-1 Social logins are worthwhile. MailChimp wrote up a compelling argument against using them but that dates to 2012 and they later acknowledged it can be useful, depending on the site.
AS-2 This TechCrunch report from 2015 is still valid that Google and Facebook are the most used social logins and others are too marginal for us to consider for initial launch.
AS-3 We will store this information and keep a user logged in as long as they are logged into the social account she selected
AS-4 We will want to encourage this option ahead of the email option because it can save time.

Believe me, I didn’t realize a seemingly simple task could carry so many assumptions! This can be so helpful.

Note Possible Constraints

A constraint is a limitation that may be outside of your control. Trying to pin these down early helps others on the team plan. I have also found it helpful to ask others if they can help identify constraints because sometimes you don’t know what you don’t know.

Constraint ID Description
CT-1 Google OAuth 2.0 limits
CT-2 Facebook guidelines for web permissions

Sample Document

I put together a Google Doc that pulls all these concepts together. Feel free to use it as a starting point any time you find yourself tasked with writing feature requirements.

View Document

Wrapping Up

I sure hope this is helpful to anyone feeling their way through feature requirements. As mentioned earlier, nothing here is meant to be prescriptive. This is only what I’ve found helpful in my early journey into product development.

That said, you may find some of these additional resources helpful:

  • Practical Design Discovery: Dan Brown writes provides a comprehensive guide on A List Apart on how to break design requirements into problem-solving principles that a team can rally around.
  • Write a Script: Chris wrote this tidbit in response to a Jeremy Keith post and serves as a good reminder that code requirements can be written narratives that follow the code structure.
  • Sketch vs. Figma: Christian Krammer compared the two apps for wireframing and it convinced me to give Figma a try.