4.1 When and How to Use Requirement Patterns 39
4.2 Tailoring Requirement Patterns 41
4.3 Writing New Requirement Patterns 42
The previous chapter gave us a tour of the machinery of requirement patterns; now let's bring them to life. The first section in this chapter invites you to sit in the driver's seat and see how patterns can help you reach your destination. In the second section we start to get our hands dirty, to let you tune patterns so that you can get the most out of them in your environment. The third section dives into the heavy engineering of building entirely new patterns.
Whatever gets you to the light 'salright, 'salright
Out the blue or out of sight 'salright, 'salright
—John Lennon
This section concentrates more on when to use requirement patterns than how, because each pattern should be its own guide on how to use it. Familiarize yourself with the patterns available to you, and then exploit them as you see fit.
Requirement patterns are first and foremost to help define what a new system needs to do. They can be used even if you're an agilist who's not writing formal requirements—in which case a requirement pattern can act directly on your thinking rather than through an intermediate step, the requirement. There are two occasions during the specifying of a system in which requirement patterns can be used:
When defining a requirement, see if a pattern for it exists to guide the specifying of that requirement. The pattern can then provide detailed suggestions on what to say, and how, what else to worry about, and extra topics to consider. Once you've decided to engage a pattern, read through the whole of it (or become familiar with everything it says, so that you don't need to read it all for every requirement of this type). That is, have the pattern in front of you and do what it tells you to.
Pay close attention to what the Extra Requirements section says, because it might have a profound impact on the nature or quality of the system that's needed. Even if you recognize the merit of the extra requirements the pattern suggests, you may not want to be sidetracked by tackling them immediately. That's fine: just make a note that it remains to be done. You also need to take on board each infrastructure on which the patterns you use depends: add it to the Infrastructures section of your requirements specification, and then make sure it is itself properly specified.
When considering the completeness of requirements, scan the set of patterns for topics to cover—to see if you've missed something, or to suggest something to add.
Secondarily, requirement patterns can also be used after the fact—that is, after the requirements have been written. The ease of doing this, and the effect, depends on whether patterns were used when specifying the requirements and, if so, how closely they were followed. The main ways of using patterns after the requirements have been written are
When reviewing a requirements specification, a pattern can help you to check the quality of specific requirements, to identify topics that have not been specified, and to understand the meaning and implications of particular requirements.
When estimating the scale of a system and the effort needed to build it, based on its requirements, you can use patterns to get a better feel for the implementation complexity.
If you have records from which you can tell how long particular features took to implement in previous projects, you can calculate the effort needed to implement an average requirement of a particular type—that is, metrics you can attach to each pattern, which would allow quick estimation of the effort for all requirements for which patterns were used. Effort figures are not available for the patterns in this book, and even if they were, they would need recalibrating to suit each organization's environment.
When implementing a requirement, a pattern can give you a deeper understanding of its intent. The "Considerations for Development" section of the pattern is aimed squarely at the designers and developers of the software. It contains hints on how to approach implementation and suggests things to bear in mind.
When testing a requirement, the "Considerations for Testing" section, which is written specifically for software testers, serves to suggest approaches to testing this kind of requirement.
If we look at a requirement, how can we tell if a pattern was used when it was written? In one sense we don't need to: after a pattern has been applied, the requirement stands on its own feet. But it's useful to know, because it lets readers know that the pattern is there to assist after the fact (points 3–6 above). There are three ways to indicate use of a pattern. First, the requirement summary can reveal it, if the summary matches a form for a particular pattern. Second, you could add a little note at the end of the requirement definition, something like "(This requirement uses the «Pattern name» pattern.)" Third, if you're using a requirements management tool, you could store the name of the pattern as an attribute behind the scenes.
Using requirement patterns has several benefits:
Requirements are easier to read—because a lot more thought can be put into producing a pattern than you can afford to spend on any single requirement.
Requirements are easier to compare with others of the same type—because they are similarly structured.
You can tell if something is missing—because comparison of the requirement against the pattern indicates if something in the pattern is missing in the requirement.
Requirements are easier to write—because you have a checklist of topics to think about. This is of greatest help to inexperienced analysts.
Readers can be referred to the written pattern for more information—about why the requirement is formulated as it is and for explanations of what each part of the requirement means.
You can refer to a list of patterns when writing your requirements specification—to check whether there are any types of requirements you should specify but that you've forgotten about.
The benefits of requirement patterns greatly outweigh the reasons for not using them—but be aware that there are a few potential drawbacks. There's a simple mantra that lets you sidestep them all: don't be lazy. Beware of the following:
You might be lulled into not thinking enough—because if you apply a pattern mechanically, especially if you copy in text from a template and fill in the blanks, you might not put your mind fully into gear.
You might misapply a pattern—if you use it in inappropriate circumstances. To guard against this, make sure you properly understand each pattern you use (especially the situations in which it's suitable), and make sure that any requirement you apply a pattern to fits the circumstances.
Lots of requirements might be worded similarly—your readers will get bored more quickly and might have less faith in what you are saying, both because they fear a lot has been copied in and may not have been properly tailored in all cases, and because you have obviously not written everything from scratch. Introduce a bit of variety into your requirements, to make reading them a little more interesting and to let your readers know you put some thought into them—and that they're not a big copy-and-paste exercise.
You won't find a pattern for every requirement. A high proportion of requirements (perhaps a majority) don't have a neat pattern that can be applied to them. Our intent in using patterns is to reduce the amount of work and do a better job wherever we can, not to apply them to everything. The proportion of requirements covered by the patterns described in this book varies considerably from system to system and could be anywhere from 15 to 65 percent. (A self-contained business system would be at the high end of that range. The less a system fits that stereotype, the lower the percentage of the requirements for which these patterns apply.) These figures come from study of real-world requirements specifications. We could write more and more patterns to cover more types of requirements, but we'd quickly reach the point where diminishing returns render it not worthwhile. A substantial system will always have many requirements that will need to be written from scratch.
For certain types of requirements, it's tempting to group them together in their own section in the requirements specification (for instance, a section for all of a system's reports). This has some advantages, such as reducing the chances of duplication (for example, specifying the same report twice in different sections), but on the whole it's preferable to keep all requirements for each functional area together. A functional area often has a constituency of users, and it's easier for these users to read the specification if every function they need is described in their section. If necessary, one section can refer to a requirement for a function that is defined in another section.
The phrasing of individual requirements is to a large extent a matter of personal preference—their author's own writing style—which we don't want to suppress unduly because it can help to enliven otherwise turgid technical documents. Phrasing also needs to suit the organization's culture, such as the appropriate degree of formality in speech. And, as always, speaking the customer's language is of overriding importance in a requirements specification. For all these reasons, the language used in the templates in requirement patterns should accord with the language used in the rest of any requirements specification that use those patterns. Sudden changes in style will strike readers as odd and make them feel uncomfortable. At worst it can be obvious that some of the specification's language comes from outside the organization, which can damage the author's credibility.
In a non-English-speaking country, a software designer who speaks English can perfectly well use a design pattern expressed in English. In the same environment, however, a requirement pattern wholly in English is acceptable only if requirements specifications are being written in English. If this isn't the case, at least the templates in the requirement patterns should be translated into the local language.
You can also refine requirement patterns based on your experience with them in your organization. Some insightful organizations take a little time to reflect on how well a just-finished project ran, to find ways of doing better in future. (This is usually called a postmortem, but I prefer to call it a "postnatal," because it's more hopeful to imply it happens after the birth of the system, rather than its death.) If any problems arose as a result of badly written requirements, you could refine any patterns that were used by adding advice to guard against that problem. If no pattern was associated with a troublesome requirement, you could consider writing one, even if it's just as a vehicle for a small piece of advice. If a pattern itself was a cause of trouble, correct it so that it won't be again.
For these reasons there's a greater need to tailor requirement patterns than design patterns. So be prepared to (and don't be scared to) do this tailoring. The fundamentals of the pattern remain the same; tailoring merely tweaks the bits that appear in requirements created using the pattern. Sometimes only the requirement definition templates need to be changed (because they're the only part that ends up in actual requirements), but then modify the examples too to reflect the changes to the templates. Also check the rest of the pattern for consistency with the modified templates, and adjust it as necessary.
Each time we tailor a requirement pattern we create a new manifestation of it. In this context we can take the term "manifestation" to mean one instance of a pattern tailored to suit a particular environment and approach. (We can't use the term "version" because each manifestation could have its own history and thus go through several versions.) In some organizations, this means that multiple manifestations of requirement patterns might be needed. If so, make sure the right ones are used for each project. Add an explanation to each one indicating which manifestation it is and when it should be used. In practice, this should be a straightforward matter if done from the moment a second manifestation of any pattern is created.
This section deals with writing one or more new requirement patterns from scratch, on fresh ground for which no patterns exist already. It doesn't cover modifying an existing pattern or creating a new manifestation or version of one. The process is divided into two stages: finding a pattern or patterns to write, and then writing a new pattern. Writing a new pattern also includes analysis and review steps, which makes the process similar in many ways to that for specifying requirements themselves.
Don't tackle new patterns lightly or just because you like the idea. Do it only if each new pattern delivers enough value to make it worthwhile. That will be a subjective judgment, based on how much time will be saved in specifying requirements of this type—how many requirements will there be, and how much time will be saved on each one?—and also how much can be gained by writing better requirements.
On the other hand, don't be put off because it sounds daunting. If, in your environment, certain types of requirements crop up repeatedly and would benefit from being specified in a consistent manner, or simply are sometimes specified badly, then go ahead and write a requirement pattern for them. It's not that hard!
Are patterns invented or are they already out there, lurking in the undergrowth waiting to be discovered? The tenet that a pattern "describes a problem that occurs over and over again in our environment" suggests we're surrounded by a menagerie of wild patterns that have yet to be captured. Yet they inhabit an artificial world of our making, a world we can strive to improve, so we're at liberty to adjust or create patterns accordingly. Capturing patterns is first a matter of hunting for them among the world of requirements already written. If we don't find what we want, we can engage in a little genetic engineering to create patterns for fashioning our brave new world.
As with any kind of hunt, there are two ways to find our quarry: the systematic—methodically scouring an area and flushing out most of its inhabitants—and the opportunistic—catching whatever we stumble upon. That's not to suggest the systematic approach is always preferable. Use them as follows:
Systematic Our aim here is to build a list of candidate requirement patterns. You might do this if you're contemplating creating a set of industry-specific and/or company-specific patterns. Gather all existing requirements specifications that you want to use as your hunting ground, and proceed through them looking for requirements in your area of interest.
Study each such requirement and try to classify it: what type is it? If an existing pattern can be applied to it, note that fact and move on. If an existing pattern doesn't quite fit, study the requirement to see if a new, more specialized pattern could be devised for it. Otherwise, can you envisage a pattern being of assistance in specifying this requirement? If so, suggest a name for this pattern and add it to the list of candidates. Don't be fussy at this stage; requirements don't always conveniently fit the patterns. Nor are there hard and fast rules for identifying patterns. When you've gone through all the available specifications, review the list of candidate patterns. You might spot some duplication or overlap. Resolve these inconsistencies.
(The patterns in this book arose in this way. I loaded sets of requirements into a spreadsheet and added a column for the name of a candidate pattern of which each requirement is an instance, where relevant. This yielded a list of patterns, which was gradually refined and improved. The spreadsheet also provided statistics on the prevalence of requirements for each pattern.)
Opportunistic When specifying a requirement, you may realize there will be others of the same type. If you find it tricky to write this type of requirement, a pattern might be worthwhile to help other people when they come to write similar requirements—and to promote consistency. For example, in a banking system, this might happen for a requirement that defines the characteristics of a type of bank account. When you identify a pattern in this way, beware of taking too blinkered a view of it. Before writing it, try to think beyond the requirement at hand. What variations might there be? Don't rush into creating a pattern that's too narrow.
If you anticipate writing more than one or two requirement patterns, it's better to do a systematic study first, rather than writing each one in isolation. This lets you see how the patterns relate to each other, and you can write them so that they fit together coherently.
Ask yourself if analysts or developers will easily understand a pattern's purpose. If it's too abstract or hard to explain in a short sentence, or if it's hard to name clearly in a way that users will understand, there might be something wrong and requirements written using the pattern might themselves be hard to understand. Consider whether the pattern can be split into two or more patterns whose purpose is clearer. You might find multiple variants of a candidate pattern, each of which fits a particular situation much more closely than one broader pattern. Several well-targeted patterns are better than one pattern that tries to cater for several situations. The tighter the fit of a pattern, the more your pattern can guide an analyst who uses it and a developer who implements the resulting requirements. On the other hand, don't divide patterns up to the point where any particular pattern has little to say: a pattern deserves to exist only if it delivers sufficient value.
Don't go overboard. Don't try to find a pattern for every requirement: they don't all deserve one. Some requirements will only ever be one-offs, whose like will never be seen again. A pattern is only worthwhile if the effort of writing it is more than offset by the benefits accrued by using it. This happens only if it is used more than a handful of times. Because a pattern is a net benefit only if the effort saved in using a pattern is greater than the effort involved in writing it, in general concentrate on the patterns that will be used most frequently.
Our patterns don't have to mirror the requirements we encounter. Keep your eyes open for superior ways of expressing requirements. One goal of requirement patterns is to specify better requirements in the future. That doesn't only mean finding easier ways to write requirements just like those written in the past—it could also mean formulating requirements in a new way.
Decide which domain each requirement pattern belongs in. Feel free to add new patterns to an existing domain, including the domains in this book, but don't do so just for convenience. If a pattern doesn't rightly belong in any existing domain, create a new one for it. If you plan to write several new patterns, assign them all to domains at the same time. Doing so might help you decide the scope of each new domain, especially since your patterns are likely to be related (and thus might belong to the same one or two domains).
This section assumes you want to write a requirement pattern for a known purpose. The best place to start is with example requirements: gather as many as you can find. Then write the rest of the pattern in order from beginning to end. There's a significant iterative element, too: revisit and refine any previously written material as appropriate. It's also far from a mechanical process; you need to devote serious thought to every stage. Here's a suggested step-by-step process for writing a requirement pattern, which reflects the way the bulk of the patterns in this book were written:
Step 1: Is there enough value in it? Before going to the trouble of writing a pattern, ask yourself whether it's likely to repay the effort. Do a quick cost-benefit analysis, based on three key factors. First, how many times will the pattern be used? Second, how much value will the pattern provide each time it's used? Third, how long will it take to write the pattern? Thus a pattern that yields little benefit each time is worthwhile if it's used a lot, and a rarely used pattern is worthwhile if it has a big payoff each time it's used. The benefits can be both in time saved when writing requirements and in improved quality, which can result in a better system and avoiding mistakes. Judging the net value is educated guesswork, but if it doesn't look promising, proceed no further.
Step 2: Create a skeleton pattern. Include all the requisite headings and the items in the "Basic Details" section. The easiest way is to copy in the contents of the requirement pattern template document. (See the Supporting Resources section of the Preface for details of where to obtain it.) Then fill in the Basic Details section.
Step 3: Write the Applicability section of the pattern. Describe what the pattern is for, taking care to be as precise as you can. Capture the essence of the pattern in the first sentence, and say more if necessary. If you find this difficult, it might be a sign that its purpose isn't as clear in your mind as you thought. Sort this out before going further.
Also, in a separate paragraph, describe what this pattern is not for—to reduce the chances of it being used in inappropriate situations. If you can't think of any such situation, that's fine: just leave out this paragraph.
Step 4: Gather example requirements. And build a list of all that you find—as many as possible, from the widest possible range of sources. Scan through old requirements specifications looking for requirements that fit the bill—that is, that are potentially instances of this pattern—and copy them into the pattern as candidate examples. Don't be fussy at this stage: don't limit yourself to requirements that conform to your notion of how this kind of requirement should be specified. Cast your net wide.
You might be unable to find any suitable existing requirements—for instance, when you have a new kind of requirement that you expect to recur in a forthcoming specification. In this case, write a few representative requirements (at least one!) and use them as your candidate examples. Before you can advise on how to write requirements of a particular type, you must be comfortable writing them yourself, be aware of possible variations, and understand what information they should contain.
Also gather possible extra requirements as you go along—that is, any requirement you encounter that is related to this topic. Create a separate list of these requirements in the Extra Requirements section of the pattern. This list is likely to be expanded in Step 9.
Step 5: Examine the example requirements. Determine what they have in common and how they vary. Identify the kinds of information they contain. Bear in mind that few real requirements are perfect: they tend to be incomplete, imprecise, hard to understand, or otherwise flawed. (If they weren't, there would be little to be gained by writing a pattern for them. Our goal is to help do better in the future.) Pay particular attention to requirements that are out of the ordinary or that tackle this topic in an unusual way. They might give you a fresh insight and lead you to realize there's another way to look at this kind of requirement than the one you had in mind.
This is a good point at which to sit back and take stock. Don't simply look for ways to explain how to write the kinds of requirement you encounter—look for better ways. Would it be more useful to restate the requirement in another form?
Step 6: Describe the items of information a requirement may contain. Distill the content of the examples into a set of distinct constituent snippets. Give each item a concise descriptive name (suitable for using in the requirement template—or, at least, one that recognizably maps to the equivalent placeholder in the template), state its purpose, and suggest what a requirement should say about it. If it's optional, say so—and, ideally, say when to include it and when it can be omitted.
Step 7: Write the requirement template(s). Start with the best (most representative and exhaustive) example requirement you can find. Devise a requirement summary format that's descriptive, concise, and distinctive, which is sometimes a tough balancing act. Then, in the description, replace each specific item of information by a descriptive placeholder in double-angled brackets (such as «Data type name»). Enclose in square brackets ([…]) each optional item and any explanatory text related to it.
You might need more than one template, but if they are radically different from one another, it might indicate that you should be writing more than one pattern. Don't act hastily: reflect on what you've uncovered. Do the two templates really represent separate topics? Could you divide the content and extra requirements in two as well? Would two patterns deserve a base requirement pattern group for any material that applies to them both? Would each of the spun-off pieces have enough to say to justify its existence? Don't split a pattern in two just because it's the logical thing to do, if it will result in feeble offspring about which there's little to say.
(One case in this book of splitting a pattern in two occurred when I was writing a capacity requirement pattern. I ran into trouble because I realized that there are two fundamentally different kinds of capacity, so I created separate patterns for dynamic capacity and static capacity. A similar split resulted in the specific authorization and configurable authorization requirement patterns. This second case deserved a requirement pattern group for common material, but the first case didn't.)
Step 8: Write the rest of the Discussion and Content sections. Ask yourself what the writer of a requirement of this type ought to worry about, which aspects they should consider, and which considerations they're liable to miss. What sorts of mistakes could an analyst make when specifying a requirement of this type (ideally based on your experience of mistakes made in the past)? Reflect on the different circumstances in which a requirement of this type might arise, taking into account different types of system, size of project, and skill and experience level of the analyst and developers. If you were sitting next to a novice analyst as they embarked on writing a requirement of this type, what would you tell them—what advice would you give them? Think about the complications that can occur in practice. If these can be serious, consider alternative ways of specifying such requirements. Turn it into a "divertive" pattern if it'll help.
Think about what a developer needs to do to implement a requirement of this type, and how a tester would test it. These things can have a major bearing on how you formulate the pattern. For instance, the performance requirement patterns in this book tend to eschew obvious quantitative targets and prefer requirements that give more helpful guidance to developers.
Step 9: Build a list of examples of potential extra requirements. Or extend it, if you've already created a list as a byproduct of Step 4. Scan the requirements specifications again. Concentrate on the requirements that follow examples of this pattern. Add to the list any requirement that is in some way related to this pattern. But look elsewhere in the specification, too; pervasive requirements can live anywhere.
Step 10: Identify candidate topics for extra requirements. What extra requirements are commonly needed—both follow-on and pervasive? Examine the list of potential extra requirements (from Step 9), and group similar requirements together. Then ask yourself what else could be said on the subject: are there any other aspects that have been missed?
If a particular kind of extra requirement is sufficiently important (that is, it occurs reasonably often, and there's a decent amount to say about it), consider writing a separate pattern for it. (The inter-system interaction requirement pattern in this book came about in this way.)
Step 11: Write the Extra Requirements section. This constitutes the bulk of the work in some patterns. First write a list of the topics for which extra requirements might be written, giving an explanation of each one. If what you have to say about a topic is too much to fit in the list, write a separate subsection for it (below the list). Include as many examples as you can—of both follow-on and pervasive requirements (if relevant). Aim to give at least one example of each possible type of extra requirement. Write example pervasive requirements in such a way that they can be pasted directly into a requirements specification. The report requirement pattern, for instance, has lots of pervasive extra requirements (for report headings, end-of-report line, date run, and such like) that are eminently suitable for reuse.
Emphasize anything in the Extra Requirements section that involves significant effort or has other important implications. Consider describing further actions the analyst might be well advised to take, such as publicizing as soon as possible the discovery of large unexpected demands on the system. If the "Examples" section is large and the "Extra Requirements" section is important, you could add a reminder at the end of the Discussion section not to overlook the Extra Requirements section.
Step 12: Write the Considerations for Development section. Discuss this with one or more senior developers. Ask them what advice they'd give to an inexperienced developer who needs to satisfy a requirement of this kind. What would they say to prompt a good solution? What implementation pitfalls are there?
Step 13: Write the Considerations for Testing section. Ask one or more senior testers what they'd tell an inexperienced tester. How would they go about testing that a system satisfies a requirement of this kind? What difficulties have they previously encountered when testing requirements of this kind? Testers are a good source of wisdom on causes of ambiguity and on what sorts of information are often omitted. Also, what advice do you have to offer?
Step 14: Was it worth it? A reader can get out only what the author puts in. If the pattern you write doesn't say enough of value, stop, file it away, and waste no more of your and other people's time on it. It's worth recording its existence, though, so that anyone with a real interest can find it. It would be a shame if someone else embarked on writing a pattern on this topic and duplicated your effort without realizing it.
(During the writing of this book several patterns fell by the wayside at various stages of development. Nearly all were dropped soon after being identified as candidate patterns and requirements were tagged as examples. They fell for several reasons, but mostly because they were too obscure or too broad in scope to be able to generalize their content. Those few that were dropped later did so mainly because there turned out to be insufficient material of value to say.)
Step 15: Have the pattern reviewed. Ask analysts to check clarity and usability. Ask software designers and engineers (and perhaps database designers, too) to check practicability and to contribute to the implementation considerations. Ask testers to check (and enrich) the testing considerations. Take review feedback seriously. Be prepared to change the whole direction of a pattern if someone finds it confusing—or even to scrap it altogether. A badly formulated pattern could have unfortunate effects in every system in which it is used.
Writing a requirement pattern is not as daunting as the length of this list would have you believe. Treat this more as a guide to things to think about. You don't have to adhere to it doggedly.