4.3 Writing New Requirement Patterns

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!

How to Find Candidate Requirement Patterns

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).

Creating a New Domain

If you've identified a new domain, first make sure it has a clear theme, one to which you can give a clear and concise name and whose role you can explain in a sentence or two. You need a document in which to describe the domain, its patterns, and any infrastructures it has. This normally means creating a new document specifically for it. But if your domain is just for one or two patterns you don't expect to be useful in other systems, you could include a section for the domain at the end of this system's requirements specification.

There are a few other things to think about:

Look at the patterns you've put in the domain and ask yourself if there are any gaps. Can you think of any other patterns that belong here?
Avoid mutual dependencies between domains as far as possible. Ways to do this include splitting a domain in two, merging two domains, or moving a pattern to a different domain.
Is any supporting infrastructure needed to implement the patterns in this domain? If so, write an overview of the infrastructure, to a similar level of detail to the infrastructure overviews in this book. If you're in the middle of specifying the requirements for a system, you probably need to add an instance of this infrastructure to it-and specify requirements for it, too.

How to Write a Requirement Pattern

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.