Monday, April 15, 2013

Requirements and Specifications

As I was saying in my last blog, I’m preparing for a talk at Skills Matter entitled: “Business Analyst, Product Manager, Product Owner, Spy!” which I should just have entitled it “Requirements: Whose job are they anyway?” and so I’ve been giving a lot of thought to requirements.

I finished the last blog entry noting that I was concerned the way I saw Behaviour Driven Development (BDD) going and I worried that was becoming a land-grab by developers on the “need side” of development. (Bear with me, I’ll come back to this point at the end.)

Something I didn’t mention in the last blog was that I thought: if I’m doing a talk about “need” I’d better clearly define Requirements from Specifications. So I turned to my bookshelves….

The first book I picked up was Mike Cohn’s User Stories Applied, the nearest thing the Agile-set has to a definitive text on requirements. I turned to the index and…. nothing. There is no mention of Specifications or of Requirements. The nearest he comes is a reference to “Requirements Engineering” efforts. Arh.

Next up Alistair Cockburn’s Writing Effective Use Case, the shortest and best reference I know to Use Cases. No mention of Specifications here either, although there are some mentions of Requirements there isn’t a definition of what Requirements are.

So now I turned to a standard textbook on requirements: Discovering Requirements: How to Specify Products and Services by Alexander and Beus-Dukis. A good start, the words Requirements and Specify are in the title. Specifications gets a mention on page 393, thats it. And even there there isn’t much to say. True Requirements runs throughout the book but doesn’t help me compare and contrast.

Now I have a lot of respect for Gojko Adzic so I picked up his Specification by Example with great hope. This has Specifications running through it like the words in seaside-rock, and there are half a dozen mentions of requirements in the index. But….

When Gojko does talk about Requirements he doesn’t clear differentiate between Requirements and Specifications. This seems sloppy to me, unusual to Gojko, but actually I think there is an important point here.

In everyday, colloquial, usage the words Requirements and Specifications are pretty interchangeable. In general teams, and Developers in particular, don’t differentiate. There are usually one or the other, or neither, and they are both about “what the software should do.” On the occasions were there are both they are overkill and form voluminous documentation (and neither gets read.)

The fact that so many prominent books duck the question of requirements and specification makes me think this is a fairly common issue. (It also makes me feel less guilty about any fuzziness in my own mind.)

To solve the issue I turned to Tom Gilb’s Competitive Engineering and true to form Tom helpfully provided definitions of both:

  • “A requirement is a stakeholder-desired, or needed, target or constraint” (page 418)
  • “A ‘specification’ communicated one or more system ideas and/or descriptions to an intended audience. A specification is usually a formal, written means for communicating information.” (page 400)
This is getting somewhere - thanks Tom. Requirements come from stakeholders, Specifications go to some audience. And the Specification is more formal.

Still its not quiet what I’m after and in the back of my mind I knew Michael Jackson had a take on this so I went in search of his writing.

Deriving Specifications from Requirements: An Example (Jackson & Zave, ACM press 1995) opens with exactly what I was looking for:

  • “A requirement is a desired relationship among phenomena of the environment of a system, to be brought about by the hardware/software machine that will be constructed and installed in the environment.
  • A specification describes machine behaviour sufficient to achieve the requirement. A specification is a restricted kind of requirement: all the environment phenomena mentioned in a specification are shared with the machine; the phenomena constrained by the specification are controlled by the machine; and the specified constraints can be determined without reference to the future. Specifications are derived from requirements by reasoning about the environment, using properties that hold independently of the behaviour of the machine.”
There we have it, and it fits with Tom’s description. Lets me summarise:
  • A requirement is a thing the business wants the system to bring about
  • A specification a restricted, more exact, statement derived from the requirement. I think its safe to assume there can be multiple specifications flowing from one requirement.
From this I think we can make a number of statements in the Agile context:
  • Agile work efforts should see requirements as goals
  • A User Story, or plain Story, may be a Requirement itself, or it might be Requirement or Specification which follows from an previous Requirement.
  • At the start of a development iteration the requirement should be clear but the specification may be worked out during the iteration by developers, testers, analysts or others.
  • Over analysis and refinement to specifications will restrict the teams ability to make trade-offs and will also prove expense as requirements change during the development effort.
  • Therefore while requirements should be know at least before the start of the iteration specifications should only be finalised during the iteration.
In discussing this on Twitter David Edwards suggested the example of a business requirement to provide a login screen. Presumably the business requirement would be something like “All users should be validated (by means of a login system).” From this would flow the need to be able to create a user, delete a user, administer a user, etc. etc. These could be thought of as requirements themselves or as specifications. Certainly what would be a specification would be something like “Ensure all passwords contain at least 8 characters and 1 numeric.”

Which bring us back to BDD.

Having worked through this I conclude that BDD is an excellent specification tool. After all BDD is an implementation of Specification by Example.

And while fleshing out specifications may lead to the discovery of new requirements, or the reconsideration of existing requirements, BDD is not primarily a requirements mechanism and probably shouldn’t be used as one.

Requirements need to be established by some other mechanism, deriving specifications from those requirements may well be done using BDD or another SbE technique.

Now, while BDD and SbE may well give Developers first class specification tools these tools should not be mistaken for requirements tools and shouldn’t be used as such.

Pheww, does that all make sense?

I need to ponder on this, I suspect there is a rich seem of insight in being clear about specifications and requirements.


  1. Allan - This makes a lot of sense. In a colloquial sense, would "specification" equate to "business logic" or "implementation"? That would seem to fit with the definition that specifications are developed by the team after the requirements are given; also that requirements should not include implementation details. If I am wrong on that point, I would appreciate some clarification. Thanks for the post!

  2. Good point Jeff, I need to think that through a little more.

    Right off my first thought is:
    - the program is the ultimate specification of what happens (provable via formal methods if you want) therefore any specification step prior to implementation could be seen as just the first action of implementation
    - this would also explain why specification steps are often completely missing, because if you don't have one you flush it out by coding and testing

    So specification would not equate to implementation but it is part of implementation.

    Business logic is more tricky, partly because it is such a loose phrase.
    Certainly the specification could contain business constraints, even elements of business processes but would it be the entire thing? I'm nor sure.


Note: only a member of this blog may post a comment.