Resources > Articles

On Reqs and Specs

Post Author
  • Pragmatic Institute is the transformational partner for today’s businesses, providing immediate impact through actionable and practical training for product, design and data teams. Our courses are taught by industry experts with decades of hands-on experience, and include a complete ecosystem of training, resources and community. This focus on dynamic instruction and continued learning has delivered impactful education to over 200,000 alumni worldwide over the last 30 years.

On Reqs and Specs

Can you believe the angst between product managers and developers? Many product managers think their developers are incompetent. The feeling is mutual: developers don’t think product managers bring any value to the process. Yet we all want to get products to market but our understanding of roles keeps getting in the way. Who writes requirements? Who writes specifications? And what’s the difference between a req and a spec?

The requirement is the problem

Product managers write terrible requirements, littered with buzz words, ambivalent language, non-specific performance parameters. They read like somewhat-technical marketing hype. And developers have to make sense of the requirements. They complain, ‘I cannot program to these requirements.’

And they’re right.

So product managers try to become more specific by writing what I call ReqSpecs. Part problem, part implementation–and impossible to use. Developers complain ‘don’t tell me how to do my job’ because the requirement now explains how the feature should be implemented.

And they’re right again.

The primary role of the product manager is to be the ‘messenger of the market’ (reference: Role of Product Management), and we must not take on additional tasks until that primary one is completed. Yet product managers frequently attend design meetings. Why? What value do they add? If product managers have time for design meetings, it had better be after they have completed their on-site visits with their market segment.

Besides, product management attending design meetings is not about getting better designed products; it’s about sharing blame for poor design. ‘What do you mean you don’t like it? You were there when we designed it!?!?!’ If product managers are creating the design, what value is development providing? Coding? If that’s all, perhaps we should just fire all the developers and outsource to India or Ireland or someplace where at least they will code to our design. That is, we’ll get exactly what we asked for without the developer’s editorial license.

Developers say they cannot program to product management’s requirements. And they’re right. What they need is a functional specification. ReqSpecs don’t solve the problem.

Let’s clarify some terms.

  • A requirement is short statement of the problem.
  • A specification is how to solve the problem.

Alan Cooper argues that most projects fail because they do not have a spec at all. This is because most companies do not have product designers or architects. Product managers create desired feature lists. Developers write code. But no one is designing anything. Would you hire a carpenter to build the house? Of course not. You would hire an architect! Yet programmers write complex software products without a design. So Cooper suggests that we add a role that is new to most development organizations: the product architect. The architect analyzes the problems that are described in the requirements and then creates a specification, at a functional level, how the problem can be solved with the product. The architect delivers a recommended approach to solving the problem, serving as the bridge between product management and development.

In Pragmatic Institute’s course Build, we teach product managers how to log market problems, distill them into the unique set of problems, and write requirements based on the market problems. Our Market Requirements Document (MRD) is a master list of all problems and the number of customer and prospect sites reporting the problem. Developers value the class as much as the product managers because eliminating dysfunction by teaching product management to deliver what developers so desperately want to know: what are the problems in the market?

The problem is the requirement

By definition, a requirement is implementation-free; that is, absent design. When developers request more specific implementation details, they’re asking for a specification instead of a requirement. In eXtreme Programming (XP), a requirement fits on an index card and is delivered in the form of a story. The requirement is also an explicit ‘agreement to discuss’ so that developers fully understand the problem.

Instead of being in the requirement, implementation details must be in the specification. A specification is the architect’s intended implementation to solve the problem. It is not an architectural blueprint of the final product.

Joel Spolsky has already written much of what I would write on specs. (I encourage you to spend some time reading the articles at Joel on Software. I defy you to find an article that doesn’t have at least one tip on creating better products.) He writes:

‘On any non-trivial project (more than about 1 week of coding or more than 1 programmer), if you don’t have a spec, you will always spend more time and create lower quality code.’ Source: http://www.joelonsoftware.com/articles/fog0000000036.html

‘A functional specification describes how a product will work entirely from the user’s perspective. It doesn’t care how the thing is implemented. It talks about features. It specifies screens, menus, dialogs, and so on. A technical specification describes the internal implementation of the program. It talks about data structures, relational database models, choice of programming languages and tools, algorithms, etc.’ Source: http://www.joelonsoftware.com/articles/fog0000000034.html

So a requirement states the problem. A specification states the solution. Joel defines two kinds of specification: functional, which is the intended approach to solving the problem, and technical, which is a detailed internal implementation.

In the end, we all have a critical role to play:

  • the product manager finds and quantifies market problems, articulating them in the form of requirements
  • the product architect (or designer) writes a functional specification describing the approach to solving the problem
  • the product developer creates a technical specification that fully describes how the functional specification will be implemented

Think developers are incompetent? Maybe they’re working in a dysfunctional environment and are frustrated themselves. Focus on market problems and you’re halfway to a reasonable solution. Design a reasonable solution to the problem and you’ll deliver a product that people want to buy.

Author

  • Pragmatic Institute is the transformational partner for today’s businesses, providing immediate impact through actionable and practical training for product, design and data teams. Our courses are taught by industry experts with decades of hands-on experience, and include a complete ecosystem of training, resources and community. This focus on dynamic instruction and continued learning has delivered impactful education to over 200,000 alumni worldwide over the last 30 years.

Author:

Other Resources in this Series

Most Recent

A dashboard on a website showcasing product management measurement
Article

Measurement-Driven Product Management

If you are a vice president, director or team leader for a product management function, one of the biggest challenges you face today is how to demonstrate the team is making a significant contribution to top line or bottom line targets. If you can’t measure your team’s effectiveness, or if you are focused on the wrong metrics, your headcount and budget allocation could be at risk.

Product life cycle: Introduction, Growth, Maturity, Decline
Article

23 Metrics Mapped to the Product Life Cycle

Learn what to measure and how to avoid vanity metrics during each stage of the product life cycle: development, launch, growth, maturity and decline. Also learn the difference between a mission and objective and how to identify which stage your product is in.
ROI of being market driven. An image with illustration dollar signs
Article

The ROI of Being Market-Driven

Market-driven companies are more profitable, twice as fast in getting new products to market, and have higher customer satisfaction levels.
Article

23 Metrics Mapped to Each Stage of the User Journey

23 metrics for the user journey, which is the path a user takes while interacting with your product (sometimes called a flow funnel).
A person holding up a sign that say who is responsible
Article

Product Marketing or Product Management

Roles Before Titles The job titles of product marketing manager and product manager are confusing enough to start raging debates about who does what. Organizations often transpose the job titles, adding to the confusion. This article

OTHER ArticleS

A dashboard on a website showcasing product management measurement
Article

Measurement-Driven Product Management

If you are a vice president, director or team leader for a product management function, one of the biggest challenges you face today is how to demonstrate the team is making a significant contribution to top line or bottom line targets. If you can’t measure your team’s effectiveness, or if you are focused on the wrong metrics, your headcount and budget allocation could be at risk.

Product life cycle: Introduction, Growth, Maturity, Decline
Article

23 Metrics Mapped to the Product Life Cycle

Learn what to measure and how to avoid vanity metrics during each stage of the product life cycle: development, launch, growth, maturity and decline. Also learn the difference between a mission and objective and how to identify which stage your product is in.

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.

Subscribe

Subscribe

Training on Your Schedule

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