User Stories vs. Requirements

Typically, requirements are more similar to user stories than are use cases. Use cases tend to flesh out requirements with a description of the system behavior needed to achieve specific requirements. Stories are defined amorphously so that they might resemble use cases, they might resemble requirements, or they might be something entirely different, such as requests for more donuts or requests to produce documentation. (We re sure this is an incredibly popular story, although it might explain why it s deemed okay to lose story cards: Customer writes documentation request story card, programmer doesn t feel like doing documentation and loses story card ”no problem!)

We ve compared stories with use cases in detail. Let s now compare stories with requirements.

The Requirement

Many a fat book has been written about the software requirement: what it is, what it isn t, what it used to be, what it is now, what it means to you, how big (or small) it is, how to measure it ”not to mention all the different types of requirements.

For all the different (and often conflicting) definitions of the requirement, one fact (even in XP) stands tall and consistent: You need them, and lots of ˜em (although in XP they aren t exactly defined in great detail, but we ll return to the XP world in just a minute . . .).

Requirements, if you re not doing XP, tend to be written in specifications (sometimes Word documents, sometimes via requirements management tools such as Requisite Pro or DOORS). The specification can then be baselined for specific releases and put within easy reach of everyone who needs to read it (e.g., on the project intranet ^[9] ). The requirements tend to be individually numbered so that they can be tracked and easily referred to. Contrast this with XP, where they are handwritten notes jotted down on cards, which, we are told, it s okay to lose. Each requirement should also be clear, concise, and unambiguous. Writing good requirements isn t difficult; in fact, it s possible to write to a simple formula and end up with requirements that are indeed clear, concise , and unambiguous. ^[10]

Just as the plant and animal kingdoms are broadly divided, requirements can be divided into functional and nonfunctional requirements. From there, further classification is dependent on the type of project.

In XP (and agile methods in general), an important development is the recognition that not all requirements will be completely identified and detailed correctly right at the start of the project. Well, okay, we ve known that has been the case all along, but now it s more acceptable ” trendy , even ”to embrace the fact, because XP tells us to embrace change and to welcome requirements creep even late in the project.

We discuss XP s approach to requirements creep in Chapter 13.

Our real point of concern, though, is that XP takes this whole thing too far, and ”by making it socially acceptable to have incomplete requirements ”may encourage ^[11] teams to embark upon the implementation of a project too early, because all the gaps can be filled in later (gaps in the requirements inevitably also mean big gaping holes in the design).

The hype behind XP has also overshadowed the fact that for the most part, it is actually possible to define most of your requirements early in the project and to get them pretty much right. A casual glance through the XP literature suggests that the Extremos fundamentally disagree with this premise . The XP philosophy is that spending lots of time analyzing requirements up front can lead to big delays and overdesign. It s strange , though, because our own experience has been that taking this requirements up front approach actually helps to bring projects in on time, clearly focused, and with just the right level of design. (We do still advocate breaking a project into small iterations, though, to avoid the big-bang delivery problem and to shield the project from the forces of change by delivering working software in smaller increments .)

Agile methods, like any other set of tools, are appropriate to a given situation- ”the right tools for the right job. XP is often touted as being suited to projects with vague requirements. Vague, however, doesn t always mean that the requirements aren t known by anyone . It may simply be that they are vaguely defined (e.g., in brief one- or two- sentence user stories).

Light Bulb

This is another circular argument behind XP. XP is supposedly suited to a project with vague requirements, but the requirements are vague (not written down in detail and agreed upon by all project stakeholders) because you re using XP.

SATIRE WARNING
Listening Without Preconceptions

Picture the scene: a gas-lit alley in 1888, with typical London smog swirling ominously around the pedestrians chattering knees.

A horse-drawn carriage bearing the royal insignia clatters past, the horses iron-clad hooves creating sparks against the smooth pebbly cobbles.

A harassed-looking police constable makes his way on foot to the scene of a nearby murder. He is met by a wild-eyed painted lady who demands to know who might have attacked her colleague and whether the attacker is going to strike again anytime soon.

I need to ask you some questions, the constable says to the woman , who has begun to calm down a little. First of all, do you have any idea who might have done this?

The woman pauses and then launches into an emotional tirade about how that should be the constable s job, surely, to find out and tell her who did this. Her harsh , uneducated East-End accent ricochets off a nearby railing, the sparks threatening to ignite the smog.

That s hardly the way it works, the tired -sounding constable explains, and adds (in a completely inappropriate explanation given the situation), You should think of me as a gestalt being, whose existence is driven only by the information given to me by street creatures such as yourself. I am a being that consists purely of information. I have no state or matter of my own. Now, I can solve this crime given the correct information, but all I do is collate whatever details are given to me ”including, one hopes, the name of the killer. I can impose my own rules and behaviors upon the information, deriving and analyzing it using my own training and in the context of other information that other people have given to me. But I cannot add my own information to the mix, for I have none ”and if I do have any, then it is my job to ignore it to the best of my abilities , such that I do not carry any misleading preconceptions about this crime or the situation herein, that may lead me erroneously to the wrong decision. Does that make sense to you now, my poor, sweet little street creature?

The woman nods sagely and says, I understand now, Constable. It is your job to ask questions, and to listen, and to reach a conclusion based upon the information given to you in the context of your investigation, and nothing else.

That s right, the constable replies, sounding surprised.

How Are Vague Requirements Handled in a Non-XP Project?

The UserStory promises as much subsequent conversation as necessary to fill in the details of what is wanted. ^[12]

In a non-XP project, ^[13] the whole attitude and approach to vague requirements is very different from an XP project. Partly this is due to the difference in documentation culture. Extremos see nothing inherently bad about the concept of oral documentation; hence, if something isn t written down, that doesn t mean (in their world) that it s vague or missing.

In a non-XP project, a vague requirement ”that is, a requirement that hasn t been written down in sufficient detail to be clear and unambiguous ”is seen as a danger signal that not enough thought has gone into it and it should be revisited at the earliest instance (particularly if it has already been factored into the project plan). A poorly defined requirement is usually a thinly disguised mass of additional requirements (rather like a warship hiding behind a small sandbank), all of which will impact the project timeline.

If we renounce the concept of fixed deadlines and chant Software is never done! ^[14] then this isn t a problem, but in most projects the management will want to know about this potentially huge delay as soon as possible.

How do you recognize a vague requirement? Well, the Extremos like to talk about code smells, so (with heavy heart) we talk about requirement smells. Actually, let s not. Let s talk about characteristics of vague requirements instead ”that s much more palatable!

One characteristic to look out for is the dreaded for example. It s always good to clarify requirements with a concrete example to illustrate the point, but examples should never be used to actually define the requirement. Examples (of the e.g. variety) tend to be incomplete lists, which imply any number of unstated requirements. Here s an example to illustrate the point:

1.4.1.3. The product shall provide the ability to connect to different types of server, e.g. FTP, BACS, SAP, JDBC.

With such a requirement, there s no indication of whether the list of server types is complete or whether other types are implied . If some types have yet to be identified and will be added later, this should be stated explicitly.

Implementing each server connection will take additional effort, so each server example should really be a separate requirement that can be individually estimated. Connecting to a JDBC-compliant database would no doubt be pretty easy, but connecting to an unfamiliar server type could involve a steep learning curve.

Vague requirements can also be spotted if they re neither estimable nor provable ”that is, it isn t possible to prove that the requirement has been fulfilled (this problem would also show up in XP, because it wouldn t be possible to write an acceptance test for an unprovable user story). So to its credit, XP actually does have a mechanism for detecting vague requirements that are neither estimable nor testable. (However, as we discussed earlier in the sidebar Anticipating Failure Modes: Not the Simplest Thing That Could Possibly Work, XP s mechanism for tackling vague requirements isn t quite the same as defining detailed requirements in a customer-friendly language such as English.)

It isn t always the case that requirements are vague simply because they re badly written. Sometimes, a vague requirement is a symptom that the analyst isn t listening to the customer (we mean the real customer in this case) or the end users. Just like the harassed police constable in the sidebar, the information you gather for your project s requirements must be based not on your own preconceptions of what they probably need, but on the actual information given to you from a variety of sources (and not just the painted ladies).

Similarly, a requirement is sometimes vague because it hasn t been thoroughly investigated. The answer to What types of server should we connect to? might be I don t know! This is the sort of situation that XP (and agile methods in general) attempt to solve. This is one of the agile goals of XP: to reduce the cost of adding new requirements later in the project.

As we discuss in Chapter 15, it s possible to address and manage change in a more robust way than simply applying all the XP practices.

In XP, the user story lacks detail, and intentionally so. Estimating user stories accurately supposedly becomes a knack that s honed over the course of the project (so on the last day of the project the team gets really good at estimating stories!). The same problems that afflict vague requirements also apply to vague user stories: They can hide entire subsystems ”months of work ”in a single sentence or in a single for example. This hidden functionality may be discovered only when it is time to flesh out the story in more detail with the promised conversation with the customer.

In theory this is okay because the project is embracing change. At the point when the required functionality is abruptly identified (to the sound of a collective Gulp! from around the table), the new functionality would be written as new stories and scheduled for a future iteration. This is fine for a project that s embracing change and plum proud of it, but in practice it sure makes a project difficult to plan.

Architecture-Shifting Requirements

It s usually the nonfunctional requirements that end up having the most impact on the architecture. For example, the user story Must be able to handle up to 3,000 transactions per minute might not be planned in until much later in the project, after a serious amount of code has been written.

Sometimes, identifying different types of requirement and classifying a set of requirements accordingly can help to establish the level of risk inherent in the project ”that is, just how many architecture-shifting nonfunctional requirements are there? A little extra time spent on this can help with prioritization of requirements (or stories) by getting the high-risk requirements out of the way first.

Without this additional piece of analysis work, the customer would almost certainly prioritize the stories in a different order, so it s definitely worth giving her this extra piece of information so she can make the best possible decision.

^[9] A handy tip here is to make sure that everyone on the team has the Web page containing the requirements bookmarked in their Web browser. If they re using Internet Explorer (IE), the bookmark (sorry, Favorite) should be placed in the Links folder so that it s permanently visible on their toolbar.

^[10] Functional requirements documents are often referred to as functional specifications. If you want to know how to write functional specifications properly, refer to this short and pithy article (which also includes a very handy functional specification template) by Dino Fancellu: http://www.softwarereality.com/lifecycle/functionalspec.jsp.

^[11] Mr. Cynical says, Absolutely does encourage and in fact ridicules any other approach.

^[12] Ron Jeffries posting to the C2 Wiki page User Story, op. cit.

^[13] There is an implicit assumption here that we are talking about well-executed non-XP projects. Our comments wouldn t hold true for bloated, waterfall-style, big-bang delivery projects, for example.

^[14] We d like to suggest, if you decide to try this, that shaving your head and dancing on the sidewalk in long orange robes while tapping on tambourines is the most appropriate attire .