Five Pitfalls of Requirement Writing

By Kerry J. Plowman October 22, 2012

Good product managers observe untapped situations in the market, form an accurate understanding of problems tied to those observations and reframe them in a requirement that makes sense to those who craft the solution.

To be properly understood, the requirement must provide all the materials necessary for a solution to be created, including the user type, the desired end result and the success measure.

A few common missteps of requirement writing, however, can mean ineffective communications that can lead to large increases in the overall time and money invested in the project. And what should be avoided is just as important to consider as what should be included.

Here are five pitfalls to avoid in order to lessen the gap between requirements and the final product.

1. Not Knowing the Audience

Marketers know that without tailoring their messaging to a target audience, they have little chance of gaining the valuable attention they seek. This is also true for product managers and their requirements documents. In most software shops, the audience is the developers, but is your documentation tailored around that target audience?

Does the writing style take into account personality styles and differing methods of comprehension? For example, does your audience contain visual learners? If yes, do you include graphics in your requirements? 

Let's take a look at a fictitious developer, Bob. One could gather the following behaviors by observing Bob at work, asking about his preferences or observing the style of his own documentation. Here is a fabricated list of personality qualities that correspond to Bob:

  • Likes to work autonomously
  • Very absorbed in his work
  • Highly creative
  • Exceptionally logical
  • Eye for detail
  • Strong conviction to own work
  • Unconcerned with diplomacy

These characteristics can lead to a document tailored so that Bob can effectively deliver on those requirements:

Order and structure. Make the document appeal to his logical side with an inclusion of concise details.

Time to read and absorb the request. Respect his autonomy and give him enough time to consume, digest and question. Often, the best responses to a document are those given three days after providing the information. Increased ownership of solutions or specifications will occur if the developer has had the time to properly formulate his solution to the requirements.

Concise, Clear Documentation. Provide a full understanding of the problem, the user and the context. Bob can then make an easier assessment of the work ahead to create the solution. Use of “the product shall” statements can help provide additional clarity.

Hard dates for functional specification completion. Providing this, along with other milestones, helps goals to be set and measured.

While these points may differ from your own requirements audience, it does bring attention to the fact that adapting to a certain learning style can drive the quality of the product with less effort—and keep Bob happier too.

2. Ambiguity

This is one of the most difficult obstacles to overcome when writing requirements. Somewhere in the middle of a design-free requirement and a functional specification is a middle point where product management ends and development begins. It’s the moment when a problem becomes a solution. In order for that transition to occur, product management must ensure that all information is provided to understand the background, intent and prioritization of a requirement. While time consuming, a good product manager will be able to justify and/or provide valid business cases for every requirement.

Natural language is prone to ambiguity, which makes the formality of the requirements document much more important. If worded correctly, multiple readers of a requirement should ultimately come to a nearly identical interpretation. Avoiding subjective words—such as “quickly,” “maximize” or “user-friendly”—will reduce the likelihood of interpretation shift.

The most effective way to avoid ambiguity is to complement the requirement with a host of user stories or use scenarios. By providing a detailed list of user stories, the developer can easily understand the intended use of the product. The software developer might have very little work experience in the target market for which the product is intended, but having insight into how a customer would potentially use a feature helps compensate for that lack of understanding.

3. Squeezing a Solution into the Problem

How many times have you seen (or written) a requirement containing a solution for the design? It really doesn’t take much:  a short reference to what the interface should look like, or a reference to where the solution should be. Adding the “how” to the “what” will be met with disdain by the developer, who believes the product manager is treading on his turf with that type of information. Ultimately, it does belong to the development side of the house.

Product managers, although well-intentioned, tend to be a “do-it-yourself” type of crowd. It seems natural to include the solution with the requirement, to alleviate the underlying concern that it will be translated incorrectly.

This good intention may cut into the developer’s creativity to solve the problem. A better method is to check for gaps between the description of the problem (the requirement) and the plan for the solution (normally the functional specification). It only makes sense that the observer of the problem verifies and possibly has final acceptance over the functional specification. This ensures the plan for the solution is valid and on track with the requirement before the work begins.

4. Not Making Form Follow Function

The “form follows function” concept from modern architecture also holds weight in the world of product management. The requirement itself must follow strict adherence to grammatical form. Writing errors reduce the perceived importance of the requirement and distract the reader away from the essence of the requirement. Let’s face it: Importance aside, requirement documents are not the most exciting things to read. Add in poor spelling and grammatical errors and you will see the reader’s level of interest plummet.

Additionally, providing a structured document, complete with full numeration of all requirements, improves the ease of collaboration. The ability to identify a requirement easily facilitates discussion and related queries. Furthermore, numeration of the requirements also makes them traceable. In fact, it is a good practice for requirements documents to include a version number, list of stakeholders, ownership change log, revision history, summary and prioritization to ensure effective administration of the document and support for the content.

5. Not Having a Holistic Approach

Requirements that do not hit the mark and fail to sell in the market do so because the feature was not conceived with the full customer experience in mind. Take the customer point of view a step further in your mental image of their imagined use of your product. Sure the customer can install product X and use it, but what if they want to do something else with that feature? What if they uninstalled it or forgot to configure it correctly or didn’t read the manual or wanted to look for online help? How would the customer use your product if they were rushed and only have 10 minutes before running to pick up the kids? What if they used your product with limited focus or enthusiasm? Would the experience be different? Put aside the logical experience and consider any possible external factors or influences on your product.

Cause and effect can also lead to issues. In product management, it can be easy to fix a symptom (effect) and not deal with the cause. Take, for example, a software console that performs tasks on workstations. Customers begin to complain that when they launch a task on the workstation, the system just hangs. Being a good product manager, you find out from technical support that the console does not hang, it is simply busy doing a system task that is not viewable by the user. Since not much can be done with that, you decide to make the system task fully visible to the user so they know what is going on at all times.

You go home early, content in the knowledge that the improved disclosure keeps customers informed and happy. But hold on! Customers still hate your console, because the system tasks keep blocking their own tasks from launching. In this case, the task-processing design was ineffective but was never identified as the root of the problem. You fixed the effect and not the cause. Thus an evaluation of any corrective measure is needed to determine if the root cause has been addressed properly.

Getting It Right

Great requirements lead to effective and cost-efficient planning of the development process. In order to ensure the best transfer of information from market to product, product management needs to document the requirements in ways that accurately define the needs of the market and allow for development creativity. By ensuring you know your audience and avoiding the other pitfalls of requirement writing, you can provide all the building blocks necessary to build the best solutions for your market.



Categories: Requirements
Kerry J. Plowman

Kerry J. Plowman

Coming from the technology sector, Kerry Plowman has held senior management roles in marketing and product management at leading tech companies such as BMC Software, McAfee and Faronics Inc. Customer advocacy, strategic planning and content creation are his primary focus. Kerry has guest lectured on industry trends, and his career has led him to live in many places including Switzerland, Spain, Sweden, The Netherlands and the United States.


Looking for the latest in product and data science? Get our articles, webinars and podcasts.