3.2 The Anatomy of a Requirement Pattern


3.2 The Anatomy of a Requirement Pattern

This section describes what a requirement pattern contains, how it is organized, and why. Bear in mind that it talks about patterns and how to write them, not the requirements that might result from a pattern. A requirement pattern is considerably more substantial than a requirement. Writing a requirement pattern is correspondingly a lot more involved, too. Indeed, writing a requirement pattern deserves much thought. To be useful as a guide to writing requirements, it needs to take into account all the situations and variations that are likely to be encountered in the type of requirement for which it's written.

A requirement pattern needs to say when to use the pattern and how to write requirements based on it. It can also give hints on how to implement and how to test requirements of this type. To convey these sorts of information, each requirement pattern contains the following sections:

  1. Basic details The pattern manifestation, owning domain, related patterns (if any), anticipated frequency of use, pattern classifications, and pattern author.

  2. Applicability In what situations can the pattern be applied? And when can it not be applied?

  3. Discussion How do we write a requirement of this type? What does a requirement of this type need to consider?

  4. Content What must a requirement of this type say? What extra things might it say? This is the main substance of the pattern.

  5. Template(s) A starting point for writing a requirement of this type-or more than one if there are distinct alternative ways.

  6. Example(s) One or more representative requirement written using this pattern.

  7. Extra requirements What sorts of requirements often follow on from a requirement of this type? And what pervasive systemwide requirements might define something for all requirements of this type?

  8. Considerations for development Hints for software designers and engineers on how to implement a requirement of this type.

  9. Considerations for testing What do we need to bear in mind when deciding how to test this type of requirement?

Preceding all of this we have the pattern name, which appears in the title of the whole pattern. Each requirement pattern needs a unique name so that it can be referred to unambiguously. A pattern name should be meaningful-to clearly capture the nature of the pattern. A pattern's name should also be as concise as possible-preferably a single word, but not more than three. It's also recommended that each pattern name be a noun-phrase. The name of a pattern for functional requirements reflects the function name (for example, "inquiry" for the pattern that guides how to specify an inquiry function).

The number of sections in each pattern has been deliberately kept to a minimum to make them as easy to read and to follow as possible.

Basic Details

The "Basic Details" section of a requirement pattern is simply a convenient vehicle for all those items that can be answered briefly (rather than clogging up our patterns with lots of tiny subsections). In fact, the items lumped together here are a mixed bag. The items indicated by an asterisk (*) are omitted from all the patterns in this book, either because they are obvious from the context (the chapter they're in) or because they're the same in every case.

Pattern manifestation*:

There can be more than one manifestation of a particular requirement pattern, which means different variants or versions. This item tells us which manifestation we have before us, to distinguish it from others. The first manifestation of a pattern is referred to as the "Standard" one. The manifestation can convey one or more of the following things:

  1. The pattern's version number.

  2. The date the pattern was last changed.

  3. The requirements approach (or author).

  4. The customer organization (company name).

  5. The requirements specification language (for example, English).

(See the "Requirement Patterns and Diversity of Approaches" section later in this chapter and "Tailoring Requirement Patterns" in Chapter 4 for more.)

"Pattern manifestation" is omitted from all the patterns in this book. All should be regarded as being "Standard."

Belongs to domain*:

Every requirement pattern belongs in a domain, and this states which one.

Many requirements for which patterns are used need some sort of supporting infrastructure. For example, requirements for reports imply the existence of an underlying reporting infrastructure for producing those reports. Requirements should be defined for the infrastructure itself. (See the next section, "Domains and Infrastructures," for more information.)

One purpose of identifying whether a particular pattern implies the presence of supporting software is to prompt you to consider whether the requirements for that software have been adequately specified.

"Belongs to domain" is omitted from all the patterns in this book because it is clear from the chapter in which the pattern resides. This item becomes essential if the domain cannot be determined from its context, such as a single pattern that resides in a stand-alone document.

Related patterns:

This lists any other requirement patterns that apply to related situations. If it would be helpful, this item can also say a little about how the patterns relate to each other.

Anticipated frequency:

How many times is this pattern likely to be used in a typical requirements specification? For rarely used patterns, this is best stated as an absolute number, or an absolute number for each occurrence of a parent requirement. For more commonly used patterns, expressing it as a percentage of the requirements is more useful and easier. Often the frequency is best expressed as a range (of absolute numbers or percentages). This item is also at liberty to point out circumstances in which the frequency might fall outside the normal range.

For most patterns, this value is indicative only; it might vary considerably from one system to another. Don't lose sleep if your number of requirements falls outside the suggested range.

The frequencies stated for the requirement patterns in this book derive from a diverse set of real-world requirements specifications. Sometimes the actual numbers encountered have been adjusted to create a broader range, to bear in mind factors not present in the specifications studied.

Pattern classifications:

Each requirement pattern can be classified in multiple ways, and this item lists all that apply to the main type of requirement covered by the pattern. No attempt is made to apply these classifications to any of the extra requirements described in the pattern. See the "Requirement Pattern Classifications" section later in this chapter for more information about how to use classifications.

Classification lists are given in a standard format of "Name: Value", separated by semicolons. For example:

Functional: Yes; Performance: Yes

This format is concise, readable, and easy to follow. It allows new classifications to be added without changing the standard structure of requirement patterns.

Pattern author*:

Knowing who wrote a pattern can help you decide whether you want to use it. For patterns written in-house, it tells you who to go to for help.

For manifestations other than the first, this identifies both the original author and who tailored it.

The pattern author is omitted from all the requirement patterns in this book but should be included in all patterns whose authorship isn't obvious.

Open table as spreadsheet

Applicability

The "Applicability" section describes the situations in which the requirement pattern can be applied. It should be clear and precise. Conciseness helps too, to let the reader form as quickly as possible a picture of when to use this pattern. It's advisable for the first sentence to capture the essence of the matter, and for the rest to clarify and expand it-just like a requirement, in fact. All such statements in this book begin with, "Use the «Pattern name» to."

Normally, a requirement pattern is applicable in only one clear situation: two different situations usually demand two different patterns. That's not to say that all the requirements that use a pattern will look the same-far from it, because there may be considerable variations between them. Some might have optional extra clauses, and they might vary greatly in their size and complexity. However, they will all share the same underlying nature.

The "Applicability" section can also state situations in which the pattern should not be used, if there's any danger of the pattern being misapplied. If there are no situations of this kind, this statement is omitted. All such statements in this book begin with, "Do not use the «Pattern name» to."

Discussion

The "Discussion" section of a requirement pattern tells you how to write a requirement of this type. It explains everything it can that's likely to help someone who wants to specify a requirement of this type. It generally opens with an overview, to set the scene. It can describe a process to follow, if figuring what to write in such a requirement isn't straightforward. It can raise topics to which to give special thought. It can mention potential pitfalls. The quantity of this discussion material can vary enormously from one requirement pattern to another: from one paragraph to many pages; it all depends on the nature of the requirement and what there can usefully be said about it.

Content

The "Content" section is a detailed list of each item of information that a requirement of this type must convey. Each content item begins with a name by which to refer to the item, followed by an indication of whether it's optional, and then general descriptive material. It is presented like this:

  1. Item 1 name Item 1 description.

  2. Item 2 name (optional) Item 2 description.

It's useful for the description to justify the item, to explain its purpose if it's not obvious: if the writer of a requirement understands why it's needed, they are more likely to write it (and to write it well). The description can also suggest what to say about the item in the requirement, offer advice, and generally say anything that might help. The order in which the elements of the content are described is implicitly the best order for them to appear in a requirement.

Template(s)

The aim of a requirement template is to allow you to copy it into a requirement description to use as a starting point. A template is a fill-in-the-blanks definition for a requirement that is deemed to be typical of the type.

The "Content" section of a pattern can describe various optional topics a requirement might need to address but that aren't relevant in all requirements. When deciding which of these topics to include in a template, our guide is efficiency: to minimize the effort in using the template. If a topic is likely to be needed in only a small percentage of requirements, it's best left out of the template. But we must bear in mind that it's much easier to delete an unwanted item than to type in an item for which we have no starting point. A useful rule of thumb is to include a starting point for a topic in the template if at least 20 percent of requirements are likely to possess it.

Be warned that templates for documents or parts of documents are dangerous, because they can lull you into avoiding the thinking you really need to do, or they give you the impression that all the thinking has already been done. Another pitfall is that you end up saying what the template writer felt should be said when they had a different situation in mind. Nevertheless, if taken with a suitably large pinch of salt, using a template can save a little time when writing a requirement.

Each template is shown within a table like the one below, which is in a form suitable for direct copying into a requirement:

Open table as spreadsheet

Summary

Definition

The format of the summary

The format of the definition

Additional explanatory notes can follow the table.

Here's an example of a template, from the inquiry requirement pattern, that demonstrates the main aspects:

Open table as spreadsheet

Summary

Definition

«Inquiry name» inquiry

There shall be an [«Inquiry name»] inquiry that shows «Information to show». Its purpose is «Business intent».

For each «Entity name», the inquiry shall show the following:

  • «Information item 1»

Both the summary and the definition can contain placeholders for variable information, which are indicated by being enclosed in double-angled brackets and in italics-for example, «Entity name» or «Description». Each placeholder must have the same name as that used in the list of content items in the "Content" section (or sufficiently similar that they can be readily matched up). The summary format typically comprises two parts:

  1. A fixed word or brief phrase related to the name of the pattern.

  2. A brief description to distinguish this requirement from all others of this type.

A template can contain optional parts: items of information that are not needed in all cases. This is indicated by surrounding each option part in square brackets: [like this]. This is indicative only; it doesn't mean that everything not in square brackets is always essential. Conversely, an optional item might be essential in a particular situation for which you're writing a requirement.

When a requirement can contain a list of items, a sequence number is added to the name of each one (as with '«Information item 1»' in the example above), to allow the template to show more than one. An ellipsis () indicates that the list continues and might contain as many items as are needed.

A requirement pattern can contain several alternative templates, each tailored to a particular situation. For example, there might be one for a simple case, one containing every possible item, and one or more in between.

Example(s)

Each requirement pattern contains at least one-usually more-example requirement definitions that demonstrate use of the pattern in practice. For instance, a typical requirement that uses the pattern may be very simple, but some might need to say more; in such a case, we might give examples of each.

Each example is shown within a box like the one below, containing information exactly as they would appear in real requirements of which they are representative:

Open table as spreadsheet

Summary

Definition

Summary for the example

The definition of the example

Anything that follows the box (like this) is explanatory material that is not part of the example requirement itself. There ought to be no need for notes to make clear the meaning of any requirement, because requirements should be self-explanatory, but notes can be used to point out an aspect of a requirement that renders it a useful example.

Example requirements need not be consistent with one another. Each one is present to demonstrate a representative situation. Spanning a range of possibilities often demands requirements from different sorts of system and sometimes requirements that conflict with one another. All examples are intended to be good examples; there are no examples of what not to do. Examples are also intended to be realistic, which means not simplified when being added to a requirement pattern. Sometimes this involves the inclusion of extra clauses that might make an example look a little long-winded; this is preferable to giving an example that says less than one would want in practice.

Some requirement patterns contain real-world examples that can be copied directly into requirements specifications and then modified as you see fit. For example, the comply-with-standard requirement pattern has examples for a range of frequently used, general-purpose standards. A list of examples, then, can serve as a body of knowledge to be tapped at will and not just as representatives that show you what such requirements might look like.

Extra Requirements

In many situations, one requirement isn't sufficient to say all that must be said: you might (or, in some cases, always) need to specify additional requirements to spell out the implications properly. The "Extra Requirements" section in a requirement pattern explains what sorts of extra requirements should be considered and in what circumstances. It provides guidance on what to do beyond simply specifying the main requirement. What other things should you think about? What more needs to be said? If there's nothing further to specify, a requirement pattern's "Extra Requirements" section can be empty.

For example, a requirement that mandates compliance with a particular standard (see the comply-with-standard requirement pattern) is rarely sufficient. Just what does that standard say? Which parts are relevant to our system? What must our system do to satisfy this standard? We need detailed requirements that reflect the answers to these questions. The "Extra Requirements" section of the comply-with-standard pattern is the place that points out what further work needs to be done.

There are two types of extra requirements:

  • Type 1: Follow-on requirements These come after the original requirement and define additional things about it. They expand the original requirement. For ease of reading, follow-on requirements should come immediately after the original requirement.

  • Type 2: Pervasive requirements These are defined once for the whole system and define things that apply implicitly to all requirements of this type. Usually there is only one pervasive requirement for a particular aspect (for example, "Every page on every report shall show the company logo"), but sometimes there are more, with each applying in clearly defined circumstances (for example, "Every page on every report to an agent shall show the agent's company logo," in addition to the previous example). The use of pervasive requirements of this sort means that each original requirement has fewer topics to cover and can be simpler. They save repetition, and as a result they avoid the chance of inconsistency in their areas.

    Pervasive requirements can also be "catch-alls" that define implicit functions for all instances of this pattern. For example, "All data shall be displayable on some inquiry or another."

An extra requirement could itself be written with the assistance of a requirement pattern. It can have extra requirements of its own.

Figure 3-1 shows how use of a pattern can result in an original requirement plus two sets of extra requirements: follow-on requirements that add details about the original requirement, and pervasive requirements that define common aspects shared by all original requirements of this type.

image from book
Figure 3-1: Pervasive and follow-on relationships between requirements

You should group related pervasive requirements together, either before all the original requirements to which they relate or after them all. The pervasive requirements for a requirement pattern might look as though they belong in the specification for an infrastructure supporting the domain in which the pattern lives, but actually they should be kept separate. The infrastructure's requirements define what the infrastructure can do; the pervasive requirements define what our system needs (because another system might use that same infrastructure differently). That's fine, although if both systems use the same instance of software that implements the infrastructure, it can impose extra functional demands on that software. In such cases, you can place the pervasive requirements in a separate "common" requirements specification that both systems refer to.

Take care to alert all readers to the presence of pervasive requirements-especially developers, because pervasive requirements often have profound design and development implications. Imagine how you'd feel upon discovering that some characteristic you demanded for every user function was possessed by none of them. So,

  1. Don't rely on readers reading the whole requirements specification. A developer might read only those parts that look relevant to them, plus the introduction.

  2. Don't bury important pervasive requirements where they might be missed (such as at the end of the requirements specification).

  3. Make references to relevant pervasive requirements from elsewhere as you see fit.

  4. Explain in the requirements specification's introduction the significance of pervasive requirements and the importance of not missing them.

  5. Consider putting all the pervasive requirements in one place and pointing all developers unequivocally to it.

  6. Consider highlighting each pervasive requirement in some way, such as a clear statement at the end of the requirement's definition. For example, "This is a pervasive requirement" or "This requirement applies across the whole system" or "This requirement applies to all user functions in the system".

An "Extra Requirements" section can contain its own example requirements to demonstrate what each kind of extra requirement might look like. If so, follow-on and pervasive requirements should be kept separate and clearly labeled so that they won't get mixed up. Example pervasive requirements are often suitable for direct copying into a requirements specification. In rare cases, the number of pervasive requirements in a pattern could run to a dozen or more.

In extreme cases, the follow-on requirements resulting from a single original requirement could involve more work than all the other requirements put together. For example, complying with a demanding standard (for, say, safety) might be a massive undertaking and much harder than building a simple system that has the functionality you need.

Considerations for Development

The "Considerations for Development" section is intended to assist a developer who needs to design and implement software to satisfy a requirement of this type. It gives them hints and suggestions and points out things not to forget. The "Considerations for Development" section should be written in the language of developers.

image from book

The best way to look at this section is as the sort of guidance a very experienced developer would give to a junior developer. If a grizzled, seen-it-all engineer were asking a wet-behind-the-ears graduate to implement a requirement of this type and giving them advice on how to tackle it, what would they say? The amount to be said varies greatly from one requirement pattern to another. In some cases, the requirement is self-explanatory; in others, there are various pitfalls to point out.

This section can also point out things that a development representative could look out for when reviewing requirements. Is a requirement being unreasonable? If it's likely to be impractical to implement, press to have the requirement changed.

Considerations for Testing

A requirement pattern is a useful place to explain how to test requirements of its type. This section is aimed at testers. It is written primarily with user acceptance testing in mind, because that's the sort of testing that can be done most closely against the requirements. But it can be used for other sorts of testing, too.

Since requirements vary considerably in their nature, they vary as much in the ways they need to be tested. Each "Considerations for Testing" section aims to convey three sorts of information:

  1. Points to look out for when reviewing a requirement of this type. If a requirement is likely to be difficult to test, suggest how it can be reframed to make testing easier.

  2. Overall guidance on how to approach the testing of this type of requirement.

  3. Notes on matters to bear in mind and (where possible) tips on how to deal with them.

Universal requirement patterns can discuss testing only in general terms-because a pattern knows nothing about a particular organization's testing practices, the testing tools it uses, the nature of the environment in which the system will run, or the nature of the system.

An organization may well find it worthwhile to tailor-or rewrite-the "Considerations for Testing" sections in its patterns to suit the ways it does testing (taking into account, in particular, whatever tools it uses for testing) and the expertise and culture of those responsible for testing. Indeed, by taking into account the organization's individual situation, it's possible to write sections that are far more than considerations for testing; they can become instructions on how to test requirements of the requisite type. If you aim to do this, you may find it more useful to leave the "Considerations for Testing" section alone and add (or replace it with) your own "Testing Instructions" section. This could be augmented by additional artifacts to use when testing this type of requirement, such as tailored forms for writing test cases.




Microsoft Press - Software Requirement Patterns
Software Requirement Patterns (Best Practices)
ISBN: 0735623988
EAN: 2147483647
Year: 2007
Pages: 110

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net