Thursday, 22 June 2017 07:28

7 Tips for Writing Better Requirements

Written by

The success or failure of a project is due, in large part, to the requirements underpinning the effort.

When written with these steps in mind, project managers are likely to get buy-in from stakeholders sooner. Additionally, the project team will experience time savings on development as well as a more comprehensive set of testing scenarios as a result of well-written requirements. Whether they’re business, functional, or performance requirements, these steps are sure to up your game and make you a more impactful Business Analyst.

1. Know Your Audience

When sitting down to begin composition of your requirements, take a moment to think about the potential readers. In most cases, your requirements will be read by leadership, project stakeholders, developers, and testers. As you consider these sub-sections of your company, reflect on the collective skill set of each group. What would they expect to see in a requirements document? What questions can you preemptively answer for each user group? How can you write to the satisfaction of each of these disparate groups?

2. Use Plain Language

Incorporating plain professional language in your business requirements will always pay dividends when attempting to satisfy colleagues across the company. The key to writing a good requirement is balance. The more technical the requirement, the more necessary it becomes to state it for even your least technical audience member plainly. A new employee should be able to read your requirement on the first day of their job and be left with a basic understanding of what should happen. At the same time, you want the requirement to be succinctly stated and contain all of the necessary technical information the developers and testers require to complete their jobs. A good example of this balance might look like this:

Req 9.0 - A section labeled “Member Details” is present on the details window outlined in Req 7.5. This section contains the following field:

  1. Date of Birth – mm/dd/yyyy
    A. When a member is a primary subscriber, this value is populated from the DB712 segment on the 1100F section of the returned member transaction file.
    B. When member is the dependent of primary subscriber, this value is populated from the DB712 segment on the 1100G section of the retuned member transaction file

In this example, I’ve provided the developers the necessary field formatting and specific data origination points to allow for mapping while still clearly and succinctly stating what should happen when this requirement is executed. A project stakeholder or new employee can look at this requirement and, while they may be unfamiliar with the referenced file, they can exactly understand what needs to occur and what the expected output should be.

3. State the Purpose in Requirement #1

In each section of your requirements document, the very first requirement should always provide a holistic picture of what is expected as it relates to the particular sub-section of the project. For example, I might be writing requirements for the creation of a new webpage. My first requirement will always outline each element on the page with a single descriptive sentence indicating what function the element serves.

This method allows everyone from testers to leadership to wrap their heads around the expected outcome at the outset, before diving into the details of each element and potentially getting lost as you take them deeper into the weeds. This requirement also serves as a touchstone for programmers and testers which provides them a high-level picture of the finished product as well as a single, easy to read a checklist of elements to address.

4. Enumerate, Then Enumerate Some More

Let’s look at the example requirement again.

Req 9.0 - A section labeled “Member Details” is present on the details window outlined in Req 7.5. This section contains the following field:

  1. Date of Birth – mm/dd/yyyy
    A. When member is the primary subscriber, this value is populated from the DB712 segment on the 1100F section of the returned member transaction file.
    B. When member is the dependent of primary subscriber, this value is populated from the DB712 segment on the 1100G section of the retuned member transaction file

Here we see a single requirement broken down into several bullet points. The singular reason for this level of delineation: testing.

When composing test scenarios, this style of enumeration is helpful when the requirement contains an if/then statement. In this case, we’re pulling the member’s date of birth into a field Depending on the member’s relationship to the primary subscriber; we have one of two locations to pull this data from.

Individuals tasked with testing this requirement will want to ensure all scenarios are accounted for. Based on this style of enumeration, a tester might compose their test script as follows:

Req 9.0.1.A - Member is subscriber, DOB is pulled from DB712 on 1100F section of member file

Req 9.0.2.B- Member is dependent, DOB is pulled from DB712 on 1100G section of member file.

This can be especially helpful I’ve included multiple elements into a single requirement. For example, I may have a date of birth, ID number, last name, and first name. I would assign a number to each of these elements and a letter to each if/then statement to help my QA analysts ensure their test scenarios are in lockstep with your requirements.

5. Make Them Specific & Definitive

When writing requirements, there’s no room for wishy-washy language or a passive tone. These requirements are the foundation for the project and absolutely must be adhered to. While it’s never advised to tell the developers exactly HOW to execute the job, it’s imperative to be specific and state the expected outcome with zero wiggle room.

Note the tone and the specificity of the following example:

Req 1.2 - End-user cannot query a future renewal date exceeding 15 days from the date of the inquiry (current date). Additionally, end-user cannot query a historical renewal date exceeding 12 months from the date of inquiry (current date).

Future Renewal Date

  1. Dates exceeding 15 days into the future are disabled on the date selection calendar control.
  2. When a future renewal date exceeding 30 days from the date of inquiry is manually entered, the following error is displayed in red text:
    “Date of service cannot be more than 30 days from today.”
  3. Any manually entered date value deviating from MM/DD/YYYY format generates validation error documented in Req 1.1.
  4. Any manually entered date value containing a non-numeric character generates validation error documented in Req 1.1.
    Historical Renewal Date
  5. Dates exceeding 12 months into the past are disabled on the date selection calendar control.
  6. When a historical renewal exceeding 12 months from the date of inquiry is manually entered, the following error is displayed in red text:
    “Date of service cannot be older than 36 months from today.” Search eligibility button remains disabled.
  7. Any manually entered date value deviating from MM/DD/YYYY format generates validation error documented in Req 1.1.
  8. Any manually entered date value containing a non-numeric character generates validation error documented in Req 1.1.

This wording of this requirement is specific and leaves no opportunity for misinterpretation by developers and testers alike.

6. Account for Edge Cases

Within the scope of any project, there will always be outlying scenarios causing unexpected outcomes. Some of which may require an almost perfect set of circumstances to occur. While these edge case scenarios may seem impossible, your project is always subject to Murphy’s Law.

I now make it a practice to consider every conceivable edge case, which often includes consulting with colleagues to brainstorm all of the ways a product could produce unwanted results. Once a comprehensive list of scenarios has complied, include them in your requirements. Some stakeholders may feel this is overkill. However, your developers and testers will appreciate the forethought.

7. State the Obvious

Both seasoned and new business analysts alike can display a tendency to assume a base level of knowledge for all project participants. For the sake of brevity, we often avoid documenting what are considered “implied requirements.” In today’s professional culture of contracted employees, we can no longer omit the obvious details. Considering the rate of churn experienced during the lifetime of a project, the risk of your audience omitting a vital detail in the development and testing of the product is significantly higher. With the addition of temporary contractors, you may find the makeup of the project team is radically different at the time of development than at inception.

Don’t be afraid to state the obvious, even if it appears unnecessary or redundant. You’re not writing a fictional short; you’re composing a vital project artifact that aims to answer every question and leave no stone unturned.
Are there any other tips you’ve found to be useful in writing your requirements?

Please share in the comments section.

Read 10141 times
Dustin Snyder

1stcontributionDustin Snyder is a Business Analyst specializing in systems change management for Blue Cross Blue Shield of Arizona. With over 20 years of experience in the insurance, IT, and software development industries, Dustin holds both ITIL and HDI Management certifications alongside a deeply held commitment to coaching for success.

© BA Times.com 2017

macgregor logo white web