Building Software Requirements

Project managers and developers alike will agree that written software requirements are critical to building a successful product. However, not enough time is spent talking about how to gather requirements from stakeholders and how to translate those requirements into written user stories. This article has 4 sections that will guide you toward improving the productivity of your development team by writing effective requirements.

  • Why are effective requirements important?
  • What is needed to write effective requirements?
  • Gathering requirements from a stakeholder
  • Writing feature requirements

Why are effective requirements important?

Written requirements are the blueprints that define the application being built.  Would you be able to remodel a kitchen without knowing the desired layout, paint colors, approximate square footage, and type of appliances?  If the answer is no, then developers should not try and build an application without a firm understanding of the business requirements for the application and each feature.

There are three main benefits of detailed written requirements:

  1. Limit re-work. It happens all the time; features are developed without a firm grasp of all of the details. Then, at a later time, an end user gets their hands on the feature and complains that it doesn’t meet their needs. The feature has to be revisited and updated, work that wasn’t accounted for in the project schedule. The goal should always be to get it right the first time.
  1. Improve team efficiency. In addition to limiting re-work, teams can be more efficient when they don’t spend time searching for details needed to implement a feature. Instead of asking person after person until they get answers, the team should be able to read the user story and start writing code immediately.
  1. Gain stakeholder trust and satisfaction. A team that has been consistently delivering applications that meet the expressed and unexpressed needs of the product owners and users will gain the trust of these key stakeholders. After trust has been established, the stakeholder will be more open to product suggestions which leads to a stronger partnership.

What is needed to write effective requirements?

It takes a lot of effort to write effective requirements and it’s not something that can be done in isolation. The most valuable skill for requirements gathering and writing is the ability to see the big picture, but also understand how each feature contributes to that picture.

To achieve big-picture thinking you need to gain an understanding of the product across 3 areas:

  • Mission and business value. Make sure the requirements will allow the feature to add as much value as possible to the overall solution. For example, if the main value of the feature is to decrease the time it takes to complete an action, then the requirements should be focused on practical usability as opposed to UI flair.
  • End users. Always consider the end users. In most cases, there are different user classes that will ultimately be interacting with the application, which can be grouped into administrators, primary users, secondary users, and tertiary users.  I think tertiary users are the most overlooked, as they usually work with an output of the application such as reports, data, and integrations with other systems. When writing requirements, make sure you understand which user will be interacting with the feature most frequently.  Then, make sure that your decisions will improve that user’s interaction with the application.
  • MVP. An MVP, or minimum viable product, is the set of functionality that will allow the application to fulfill its mission and start delivering business value. There are always additional features, or additional aspects of a feature, that are tempting to include when writing requirements. However, it’s important the critical functionality needed for the MVP is developed first because it’s the foundation that the rest of the application will be built on. Striving to get an MVP in end users hands as quickly as possible will pay dividends in the long run, because you can use the feedback to determine which enhancements are most important and gain some insight into the requirements that will benefit the primary users.


Gathering requirements from a stakeholder

I mentioned earlier that writing effective requirements can not be done in isolation. It’s a collaborative effort with key stakeholders to gain the understanding outlined in the previous section. There are many different ways to work with stakeholders to gather requirements, and a productive backlog grooming session is one way to achieve a clear understanding.

Backlog grooming sessions are recurring meetings with the key product stakeholders, and the purpose is to continue to refine the features in the backlog and the specific requirements for each of those features. Here are four tips to help you run a successful backlog grooming session.

  • Recurring and treated with a high priority. Start by setting a recurring meeting for the backlog grooming sessions, either weekly or bi-weekly, and hold all invitees accountable for attending. These meetings frequently turn into a brainstorming and/or design session, and you need all stakeholders in the room to come up with the optimal solution. I mentioned earlier that effective requirements are key to a successful product, and thus well-attended backlog grooming sessions are also key to a successful product.
  • Focused with an agenda of features to discuss. While it’s great for a backlog grooming meeting to turn into a brainstorming session, it’s important that it’s focused brainstorming. You should have an agenda of features to discuss in the meeting, and if the conversation strays too far from that agenda then refocus the meeting. Base your agenda on the features being developed in the upcoming weeks, with a higher priority placed on items you haven’t discussed in detail before.
  • Have the right people in the room.  Since these backlog grooming meetings are where most of the detailed requirements are discussed and agreed upon, it’s important that the attendees are able to provide information and answer any questions that might come up. The product owner is an obvious person to include. I’ve had great success with bringing in end users of the application, or future end users of the application, to provide their input into the discussion. If the application will be integrating with other systems, it can also be beneficial to have an SME from the other applications for parts of the conversations. One way to manage the attendees is to have a baseline group, and then bring in additional users and/or SMEs based on the agenda for each meeting.
  • Follow up with notes and action items. Personally, I think this is the most critical aspect of a successful backlog grooming meeting. You should send a detailed set of notes (or detailed tickets that were discussed) and action items to all attendees of the meeting, along with any product stakeholders that were not able to make the meeting. This will prevent confusion or miscommunication that could have happened in the initial meeting, as everyone will have a chance to read through this output at their own speed. It will also allow you to reference notes when you are writing the detailed requirements and can help answer the “why” behind some of the questions that may come up.


Writing feature requirements

Now that we’ve discussed why good requirements are important and how to gather requirements from product stakeholders, it’s time to focus on writing feature requirements that will be handed off to the development team.

The first question that comes to mind is “what is a good requirement”?  I think there are three parts that make up a complete feature requirement:

  1. Readability. It’s important that a developer is able to fully comprehend the feature requirements at a high level, so they can make implementation decisions that will maximize the value of the feature. If a requirement is ambiguous or difficult to understand, then it may be misinterpreted or not read in its entirety.
  1. Detailed. While a developer needs to understand the feature at a high level, they also need to understand the details that make up the overall feature. If details are missing, it may result in buggy or haphazard design.
  1. Specificity. If a feature requirement lacks specificity, it will result in something being built other than what was intended. The details in the ticket need to be specific and focused to provide supporting information to the overall feature.

When writing user stories or feature requirements, I like to include the following sections where applicable. These sections will help ensure that the 3 criteria listed above are met.

  • High level overview and business value for the user. The high level overview should be a few sentences to a paragraph that explains the feature that will be implemented. It should also include the business value that the feature will add. This sets the stage for the ticket and the following sections will add the additional details to support the overview.
  • Outline of each part. In a lot of cases, features can be broken down into multiple parts which will help establish the understanding of the feature. This section will reinforce the high level overview. An example feature might have the following parts:  1) add a button to the page, 2) validation logic for when the button is clicked 3) UI change that happens when the button is clicked 4) backend/API call for when the button is clicked.
  • Detailed explanation of each part. This section will elaborate on each part listed in the outline above. This is where you start to explain the real details of the feature and group the details into the parts you identified above. I like this approach as it makes the details more consumable since they are tied back to a smaller aspect of the overall feature.
  • Technical implementation guidelines. The technical implementation guidelines are more applicable when there is a technical lead on the team that isn’t necessarily a full-time developer, which is how we run projects at Headspring. This section allows the tech lead to provide guidance on different technologies to include, specific areas of the code to reference where similar logic already exists, or just overall guidance for what they are expecting in the implementation. It’s not a hard set of rules, just a starting place for the developer to start thinking about the solution.
  • Acceptance criteria and how to test.  This section is to ensure the feature was built to specifications. Provide a list of criteria and test cases to run through after development so the team member can ensure the feature is functioning correctly. An example could be “when the add row button is clicked, the new row is displayed in the table.” It’s helpful to include edge cases and unhappy path cases that might not have been considered in the initial implementation. If there are a lot of steps that need to happen in order to verify a feature, use this section to list in-depth test cases to run through in testing.
  • Supporting documents. Finally, any supporting documents that would be beneficial to the developer should be attached to the requirements. The most common document will be in the form of visual mockups to give the team an idea of how the feature should look. I think mockups are incredibly helpful to the understanding of the feature and we should create them as often as possible. Even if it’s a sketch or rough mockup using a tool like Balsimiq, visuals can help enforce the details listed in the previous sections.


I hope this post has given some insight into the process of writing effective software requirements and helps your team create better products in the future.


Let's Talk