Specifying Nonfunctional Requirements with Planguage

Karl Wiegers
Feb 16 · 5 min read

How often has a customer asked you to write software that is user-friendly, robust, fast, or secure? Everyone will agree those are worthy properties we all want in our products. However, simply stated like that, they are terrible requirements! Those vague words give you no idea of just what “user-friendly” means or how to tell if you’ve achieved the characteristics that mean “robust” to a particular customer.

Hearing such requests from users should stimulate a business analyst to explore what, say, user-friendly means to the speaker. Even then, though, many BAs still write fuzzy quality attribute requirements that don’t clearly convey expectations to developers and testers. Statements like “The system shall be user-friendly” also are unverifiable. You can’t evaluate a product to judge whether it satisfies vague quality requirements like these.

To address the problem of ambiguous and incomplete nonfunctional requirements, consultant and author Tom Gilb developed Planguage, a notation with a rich set of keywords that permits precise statements of quality attributes and other project goals. For a comprehensive discussion see Gilb’s book Competitive Engineering: A Handbook for Systems Engineering, Requirements Engineering, and Software Engineering Using Planguage (Butterworth-Heinemann, 1995).

In fact, you can use the Planguage notation to describe just about anything — not just software requirements — in a precise, multidimensional way. It’s a versatile technique for whenever unambiguous technical communication is necessary.

Keywords

TAG: Performance.Report.ResponseTime

AMBITION: Fast response time to generate accounting reports on the base user platform.

SCALE: Seconds of elapsed time between pressing the Enter key or clicking OK to request a report and the beginning of the display of the report.

METER: Stopwatch testing performed on 30 test reports that represent a defined usage operational profile for a field office accountant.

GOAL: No more than 7 seconds for 95 percent of reports. ← Field Office Manager

STRETCH: No more than 2 seconds for predefined reports, 5 seconds for all reports.

WISH: No more than 1 second for all reports.

base user platform DEFINED: Quad-core processor, 8GB memory, Windows 10, QueryGen 3.3 running, single user, at least 50 percent of system memory and 70 percent of system CPU capacity free, network connection speed of at least 50 Mbps.

You identify each requirement with a unique and meaningful tag, or label, using a hierarchical naming convention. Requirement labels like Performance.Report.ResponseTime are long but self-explanatory. The ambition states the purpose or objective of the system that leads to this requirement. Scale defines the units of measurement and meter describes how to make the measurements.

All stakeholders must have the same understanding of what “performance” means. Suppose a user interprets the measurement to be from the time that he presses the Enter key until the complete report appears, rather than until the beginning of the report display, as stated in this example. The developer might claim the requirement is satisfied, whereas the user insists that it is not. Unambiguous quality requirements and measurements prevent these sorts of debates.

Shades of Gray

The goal criterion is the minimum acceptable achievement level. The requirement isn’t satisfied unless every goal condition is completely satisfied, so make sure the goals are justifiable in terms of real business needs. An alternative way to state the goal requirement is to define the fail (another Planguage keyword) condition: “More than 7 seconds on more than 5 percent of all reports.” The stretch value describes a more desirable performance objective, and the wish value represents the ideal outcome.

Consider showing the origin of performance goals. The “←” symbol following the goal criterion shows that it came from the Field Office Manager. Also, any specialized terms in the Planguage statement are defined to make them clear to the reader. This example provides a definition of something called the Base User Platform on which the test is to be conducted.

This unfamiliar notation is intimidating to some people. Clearly, it takes more work to specify requirements this precisely. Other people, though, recognize the merits immediately.

I always introduce Planguage when I describe quality attribute requirements in my training classes. I encourage students to give it a try when we’re doing a practice session on writing quality requirements. When I taught a class at a high-tech company that makes electron microscopes, the entire class decided then and there to adopt Planguage. They recognized how superior it was to their current approach for writing these all-important nonfunctional requirements.

Planguage includes many additional keywords to provide flexibility and precision in specifying unambiguous quality attribute requirements, and even business objectives. You don’t need more than a handful of the keywords to get started though.

The main drawback to using Planguage is that the resulting requirements are much bulkier than simple quality requirement statements. However, the richness of information provided outweighs this inconvenience.

Even if you don’t write the quality requirements using the full Planguage formalism, using the keywords to think through exactly what people mean by “fast” will yield much more precise and shared expectations. And that’s what requirements engineering is all about.

=====================

This article is adapted from Software Requirements, 3rd Edition by Karl Wiegers and Joy Beatty. If you’re interested in software requirements, business analysis, project management, software quality, or consulting, Process Impact provides numerous useful publications, downloads, and other resources.

Data Driven Investor

from confusion to clarity not insanity

Karl Wiegers

Written by

I’ve written on software development and management, consulting, self-help, chemistry, military history, and a mystery novel. More info at karlwiegers.com.

Data Driven Investor

from confusion to clarity not insanity

More From Medium

More from Data Driven Investor

More from Data Driven Investor

More from Data Driven Investor

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade