Four Tips for Writing Clear, Accurate Product Requirements to Ensure Quality

Photo of colorful book stack with bookmarks and labels with REQUIREMENTS conceptual words

I recently installed a GPS tracker on my smartphone to bring on bicycling trips. While I don’t need GPS to find my way on my bike, I do find value in seeing the “trail” I ended up making to get where I was going. My tendency to want to review the path I was on comes from a realization that the path we take and the path we planned to take, can be somewhat different. That even a relatively straight path can have some unexpected turns.

Software engineering is surprisingly similar. All the effort that might go into leading a new development project in an intended direction may miss some of your projected turns. Or, since great ideas can strike at any time, you may decide to intentionally switch course somewhere along the way. In a fast-paced, innovative development environment, this is not a problem — provided there is some record of your meandering trail. In software development, our maps, so to speak, are those resources generally referred to as “the requirements”.

SIDEBAR: [We should acknowledge that not everyone works from an actual requirements document. In Agile development environments, requirements may be spelled out in general terms in a short document, but they are always more thoroughly described in the Acceptance Criteria of their User Stories. For this discussion, I am considering any resource that prescribes how an application should work as “the requirements” of the application. ]

However, software product requirements are not just for directing development, they form the foundation of reliable quality assurance testing. In fact, no reliable test of an application can even be created unless there is a specific requirement to base the test upon. Therefore, how requirements are written is vital to quality. Consider these four important tips when writing useful requirements.

Tip 1: Center each requirement on user actions AND the desired result.

When QA plans their testing, they will create a test plan. At the heart of a test plan, are test cases. A test case, in the most general terms, is a statement where specific actions are taken by a user (even if that user is an automated program) that lead to specific and measurable results. Each test case is exactly one set of specific actions and their corresponding results. Therefore, if either of these components, the actions or results, cannot be determined by simply consulting product requirements, QA’s work will be inconsistent and unreliable.

Tip 2: Be as specific as possible.

Let’s analyze an example. Imagine you are working on a project where an application is allowing users to search a database of articles pertaining to various medical conditions. The hope is that users would be able to enter symptoms they are experiencing and retrieve articles relevant to their conditions. Imagine, therefore, that the requirements documentation, in whatever form it comes, states “users will be allowed to search for articles related to various medical conditions.” One must realize that while the above statement might be useful in an outline of desired features to be included in the application, it would not enable QA to create any valid testing of this feature.

Why? There are just too many unanswered questions. The first being, “how does the user perform the search?”. Even if we assume that a text input and some button to begin the search is provided, there is not enough to specify that a certain action taken by the user will lead to a measurable result.

The questions wouldn’t stop there. “will article titles be displayed or the full article?”, “will the search be formed only on the titles of the articles or will there be a deep search of words in the article?”. These are just a few of the other questions still dangling precariously in the air. In truth, something as potentially complex as a search function will probably need a lengthy set of requirements detailing what kinds of input it will accept and what behaviors will result. If this does not happen, QA will have to keep test cases very general as far as what inputs and what results they will accept. And their testing may be too broad and nonspecific to verify quality.

Tip 3: But…don’t overthink it.

“But wait!”, some may say, “I don’t want every detail of the application dictated to me ahead of time. There will be no room for creativity.”

The point is well taken. The only thing worse than planning too little is over-planning. With a few exceptions, specifying every detail of how an application works in volumes of documentation is a good way to make bad software. It’s also impractical and exhausting, especially when you want to encourage innovation and efficiency.

Tip 4: Create ‘Living’ Documents

I contend that any product requirements documentation should start out as specific to the customer or product owner’s directives as possible, while still considering requirements as “living documents”. Simple statements describing only what features are desired gives development an idea of what is preferred without squelching creativity. This is a great starting point. However, requirements must follow the trail a project is taking as well. What begins as simple statements must be revisited and “flushed out” by amending the requirements as a result of collaboration among development, quality assurance, and product owners. As the application begins to take shape, actions and results can be decided upon as the whole team moves forward. In an Agile environment, this may be accomplished by creating a simple, 1-2 page requirements document for use as a guide to create user stories. As those user stories are completed, and new ideas are introduced, any additional acceptance criteria or specificity that can be added to the requirements can be added as needed. Ultimately, producing User Stories that reflect innovation and discovery, while containing concrete and specific details quality assurance can use to create relevant and focused tests.

If we see requirements documentation as a rough guide that is neither too rigid nor too vague to be acted upon, and we have the freedom to add to it as appropriate, neither planning nor innovation need to be sacrificed in the effort to succeed in software projects. In this way, your team can get to your intended destination together without fearing a few unexpected turns along the way.

About Aaron Priest

Aaron PriestFor as long as I can remember, I have been curious about how things work. In fact, it was a curiosity about the software I was dealing with every day that lead me from a career in education to learning how software and its related mechanisms work. As a Quality Assurance Test Engineer for Saturn Systems, analyzing software, both where it works and where is doesn’t, is a part of my everyday experience. However, I was surprised to discover that the most fascinating aspect of software development is the human beings that make it. How people work individually and how they work in teams to accomplish a goal can be as intriguing as the latest technology. I enjoy discussing not only software, its nuances and pitfalls, but also the journey people take from simple ideas to making useful creations.

Leave a Reply

Your email address will not be published.