Publishers of technology books, eBooks, and videos for creative people

Home > Articles > Design > Voices That Matter

  • Print
  • + Share This
This chapter is from the book

Functional Specifications

Functional specifications have something of a bad reputation in certain quarters. Programmers often hate specs because they tend to be terribly dull, and the time spent reading them is time taken away from producing code. As a result, specs go unread, which in turn reinforces the impression that producing them is a waste of time—because it is! A bad approach to specs becomes a self-fulfilling prophecy.

One complaint about functional specifications is that they don’t reflect the actual product. Things change during implementation. Everybody understands this—it’s the nature of working with technology. Sometimes something you thought would work didn’t, or more likely didn’t quite work the way you thought it would. This, however, is not a reason to abandon writing specs as a lost cause. Instead, it highlights the importance of specs that actually work. When things change during implementation, the answer is not to throw up your hands and declare the futility of writing specs. The answer is to make the process of defining specifications lightweight enough that the spec doesn’t become a project separate from developing the product itself.

In other words, documentation won’t solve your problems. Definition will. It’s not about volume or detail. It’s about clarity and accuracy. Specs don’t have to embody every aspect of the product—just the ones that need definition to avoid confusion in the design and development process. And specs don’t need to capture some idealized future state for the product—just the decisions that have been made in the course of creating it.

Writing It Down

No matter how large or complex the project may be, a few general rules apply to writing any kind of requirements.

Be positive. Instead of describing a bad thing the system shouldn’t do, describe what it will do to prevent that bad thing. For example, instead of this:

  • The system will not allow the user to purchase a kite without kite string.

This would be better:

  • The system will direct the user to the kite string page if the user tries to buy a kite without string.

Be specific. Leaving as little as possible open to interpretation is the only way we can determine whether a requirement has been fulfilled.

Compare these examples:

  1. The most popular videos will be highlighted.
  2. Videos with the most views in the last week will appear at the top of the list.

The first example seems to identify a clear requirement, but it does not take much investigation to start poking holes in it. What counts as popular? Videos with the most comments? The ones with the most “like” votes? And what constitutes highlighting them?

The second example defines our goal in specific detail, defining what we mean by popular and describing a mechanism for highlighting. By removing the possibility of differing interpretations, the second requirement neatly skirts the kinds of arguments likely to crop up during or after implementation.

Avoid subjective language. This is really just another way of being specific and removing ambiguity—and therefore the possibility for misinterpretation—from the requirements.

Here’s a highly subjective requirement:

  • The site will have a hip, flashy style.

Requirements must be falsifiable—that is, it must be possible to demonstrate when a requirement has not been met. It’s difficult to demonstrate whether subjective qualities like hip and flashy have been fulfilled. My idea of hipness probably doesn’t match yours, and most likely the CEO has another idea entirely.

This doesn’t mean you can’t require that your site be hip. You just have to find ways to specify which criteria will be applied:

  • The site will meet the hipness expectations of Wayne, the mail clerk.

Wayne normally wouldn’t have any say about the project, but our project sponsor clearly respects his sense of hipness. Hopefully it’s the same sense our users have. But the requirement is still rather arbitrary because we’re relying on Wayne’s approval instead of criteria that can be more objectively defined. So perhaps this requirement would be best of all:

  • The look of the site will conform to the company branding guidelines document.

The whole concept of hipness has now disappeared entirely from the requirement. Instead, we have a clear, unambiguous reference to established guidelines. To make sure the branding guidelines are sufficiently hip, the VP of marketing may consult Wayne the mail clerk, or she may consult her teenage daughter, or she may even consult some user research findings. It’s up to her. But now we can say definitively whether the requirement has been met.

We can also eliminate subjectivity by defining some requirements quantitatively. Just as success metrics make strategic goals quantifiable, defining a requirement in quantitative terms can help us identify whether we’ve met the requirement. For example, instead of requiring that the system have “a high level of performance,” we can require that the system be designed to support at least 1,000 simultaneous users. If the final product only allows three-digit user numbers, we can tell the requirement hasn’t been met.

  • + Share This
  • 🔖 Save To Your Account