Resources > Articles

Five Pitfalls of Requirement Writing


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. Requirement 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. Requirements Without 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.

  • 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.


Other Resources in this Series

Most Recent

Is Your Training Budget Going to Waste?

Is Your Training Budget Going to Waste? How to Calculate Training ROI 

The latest report from Training magazine has some news – U.S. companies have, for the first time, spent over $100 billion on training.  So, why the big spend? In the fast-paced, competitive business world, companies...
: OpenAI's ChatGPT Enterprise Takes Center Stage

How ChatGPT Enterprise Addresses Key Concerns in Generative AI

OpenAI just released ChatGPT Enterprise, a business-oriented upgrade of its popular AI chatbot—make no mistake, this is a big deal. 
AI and Product Management

AI and Product Management: Navigating Ethical Considerations 

Explore the critical aspects of AI product management, its challenges, and strategies for ensuring responsible and successful implementation.
How to learn AI for Product Managers

How to Learn AI as a Product Manager: Start Here 

As a product manager, harnessing the power of AI can be a game-changer for your product. Whether automating mundane tasks, providing personalized experiences or making data-driven decisions, AI has many applications that can propel your...
Category: AI

Beyond SEO: Driving Customer Attraction, Retention and Top-Line Growth

Does your website speak to your customers and fulfill your business objectives?

OTHER ArticleS

Is Your Training Budget Going to Waste?

Is Your Training Budget Going to Waste? How to Calculate Training ROI 

The latest report from Training magazine has some news – U.S. companies have, for the first time, spent over $100 billion on training.  So, why the big spend? In the fast-paced, competitive business world, companies...
: OpenAI's ChatGPT Enterprise Takes Center Stage

How ChatGPT Enterprise Addresses Key Concerns in Generative AI

OpenAI just released ChatGPT Enterprise, a business-oriented upgrade of its popular AI chatbot—make no mistake, this is a big deal. 

Sign up to stay up to date on the latest industry best practices.

Sign up to received invites to upcoming webinars, updates on our recent podcast episodes and the latest on industry best practices.



Training on Your Schedule

Fill out the form today and our sales team will help you schedule your private Pragmatic training today.