Synopsis of "The Contents of a Requirements Specification"

This chapter discusses what a requirements specification should contain. As with Chapter 1, it is a synopsis of a full version of the chapter that can be downloaded from the book’s associated Web page at http://www.microsoft.com/mspress/companion/9780735623989. (See the Preface for more information.) The synopsis is a flying overview. The full version goes into considerably more detail and is intended primarily as a reference, to call upon when you want advice on what to put into a particular section and why. Both versions are structured in a similar manner to the kind of requirements specification that this chapter presents.

There’s no single right way to organize a requirements specification, but certain topics recur in most systems and deserve their own sections. Figure 2-1 shows a suggested structure for a requirements specification, in the form of a table of contents that identifies thirteen key topics described in this chapter.

Figure 2-1 Suggested structure of a requirements specification, with thirteen kinds of sections

The sections with grayed-out names are optional; include them as appropriate. In practice, all the top-level sections (except those in the “Introduction” and perhaps the “Context” section) will have extra subsections; some are likely to have many. This structure has worked well in practice, is clean and straightforward, and every section is present for a good reason. But no way of organizing a requirements specification is perfect for all occasions, so feel free to adjust it. Treat the thirteen key topics as parts that you can assemble in whatever way suits you: leave out parts that your system doesn’t need, and merge parts together if each one is too small to justify its own section.

There are four types of top-level sections, which mirror the four top-level sections that follow in this chapter: “Introduction,” “Context,” functional areas (which do the hard work of specifying what the system must actually do and where the bulk of the requirements reside), and “Major Nonfunctional Capabilities.”

2.1 Introduction Section

This section deals with six topics that belong in the introduction of nearly every requirements specification: system purpose, document purpose, requirement format, glossary, references, and document history.

System Purpose

A requirements specification should open with a description of what the system is for: who wants it, and why? Who will use it? What is the business motivation behind it? These sound like obvious questions, but it’s surprising for how many systems they’re not asked directly—perhaps because they are too obvious. And these questions sound as though they should be easy to answer, but frequently, they’re not. Even when they have been answered, there might be much disagreement over the answers—which hints at deeper misunderstandings or disagreements among stakeholders.

Give this section a title that spells out clearly what it’s for: “The Purpose of the «System name» System” or something very similar. This is to spur you to answer the question of what the system is for and to improve the chances that someone will notice if it hasn’t been answered. Titling this section “Scope” or “Overview” leaves its true goal vague, which encourages uninformative waffling, especially when using a fill-in-the-blanks template. I suggest including the name of the system in the title of this section because some specifications make it hard work to unearth the system’s name. Also take care to describe the purpose of the system itself, not the purpose of a project to implement the system.

Document Purpose

Every technical document should state clearly what it’s for—the role the document plays. The best way to do this is to include in the opening of the document a section called "The Purpose of this Document" or something similar, so there’s no question what the section is for. You, the author of this section, are its initial audience: use it to force yourself to confront the task at hand, and think about what you’re doing. This section makes clear the role a requirements specification plays and more specifically, the role this requirements specification plays for this system, which might entail further explanation.

You must assume that much of your audience doesn’t know what requirements are about or what a requirements specification is for, so you need to explain. Do so briefly and concisely, because if you ramble on, most readers will miss your main points. Beware of people who think they already know, but who perhaps don’t appreciate the distinction we make between problem and solution. For their benefit, take care to make the explanation clear and strong. Begin by saying something like this:

The purpose of this document is to state the requirements that the «System name» system must satisfy. Its role is to describe the problem to be solved, not the solution: what the system must do, not how.

Other matters to consider addressing in this section are: (a) identify the audience; (b) state disclaimers; (c) say a little about the document’s structure; and (d) identify other relevant requirements specifications.

Requirement Format

Much of our audience for requirements either has no idea or doesn’t properly understand what a formal requirement is. You must explain, and including a section called "The Format of Requirement Definitions" in the introduction of the requirements specification is the best way. It needs to do the following:

• Explain that the material in the specification is split into formal and informal parts.

• Describe the items of information given for each requirement.

• Explain that each requirement defines a single measurable objective.

This book advocates writing the following four items of information for each requirement and presenting them in the form of a word processor table:

Item 1: Requirement ID This is a unique identifier that enables us to refer to each requirement unambiguously. Without an ID, a requirement can’t be traced or managed, can be lost, and commands no respect. The first essential quality requirement IDs need is to be unique: no two requirements can have the same ID. Whenever we talk about a unique ID, we need to clearly understand the scope of that uniqueness. Requirement IDs also need to be convenient to use, which means they should be concise, distinctive, and sequential. A lesser consideration is that requirement IDs should be groupable, so we can refer to all the requirements in a particular section in a specification. Requirements also evolve. The full version of this chapter also discusses strategies for renumbering requirements when you add to them and for handling the removal of requirements. The requirements specification itself needs to explain the requirement ID format that it uses, or it can refer to a separate document that explains it.

Item 2: Definition This is the description, in free-form text, that formally defines the requirement. The requirement definitions are what our requirements specification exists for; the rest of the document is merely a vehicle for them—albeit with a smooth ride and luxury upholstery, if we do a good job. The formal elements in the definition of a requirement are: a formal statement of the requirement plus (optionally) a restatement of the formal requirement in different words, and extra details. The definition can then contain any of the following informal things: an example (or more than one); the rationale, motivation, or intent of the requirement; further justification for the requirement’s existence; justification for the requirement’s form; resolution of contradictions (real and apparent); relationships with other requirements (if helpful to the reader); suggestions for implementation; justification of priority; and deletion details (if it’s deleted). All of these items are explained in the full version of this chapter. This list might look daunting, but no requirement needs all these.

Item 3: Priority This states how important the requirement is. Prioritizing requirements provides a sound basis for making sensible decisions about how to build our system (including the order in which to build the parts). Before we can assign a priority to any requirement, we must define the priorities we wish to use and explain them to our readers.

Item 4: Summary description This sums up the requirement as briefly as possible (using two to six words). This improves the readability of the specification and makes it easier to find a particular requirement.

It’s possible to squeeze all sorts of other things into a requirement, and for sound reasons, some experts advocate doing so.

The example requirements given throughout the book give only the summary and definition. The requirement ID and priority are omitted because they make no sense in this context.

Glossary

A glossary is often an afterthought that appears by accident or because it makes a document look more weighty or because a document template has a section for it that has to be filled in. This is a mistake, and it explains why so many glossaries are awful. A good glossary in a requirements specification deserves just as much care as any other section. It plays several different roles: establishing the meaning of each relevant term, educating uninformed readers, demolishing misconceptions, and forcing poorly understood domain concepts out into the open. A glossary isn’t simply a list of terms. It deserves an introduction, which can include: the scope of the glossary, references to other glossaries, instructions, and disclaimers.

The key to deciding whether to include a candidate term in our glossary is relevance. Define just the terms you use or those that are likely to be used throughout the system—and no more.

An entry in a glossary comprises two parts: the term itself and its definition. When writing a definition, assume nothing. We want our requirements specification to be intelligible by a smart but uninformed audience. No business or technical term is so obvious that everyone knows it. The key to writing a good definition is precision. The first sentence should constitute the formal definition of the term. If you feel you need to reinforce it to make it clear, follow the main definition with a restatement of the term in another form. After that, add whichever of the following might be useful: an example of usage; references to related term(s); scope (that is, the domain within which the definition applies); part of speech (noun or a verb, if it’s not obvious); a note on spelling; and the definition’s origin.

Having defined a term in the glossary, do not use that term to mean something else in any document whose scope is covered by the glossary. Our goal is to maintain consistency throughout our requirements specification and throughout the system as a whole.

References

Use the “References” section to identify documents and other sources used in the process of writing this document. A list of references is often self-explanatory, but you can introduce it by saying a little about what qualifies a document to be included in the list.

For each reference, provide enough information to identify it unambiguously, which means that you must supply more than just its title. Writers of internal documents within an organization are often slack in including identification details in their documents; they are liable to omit date, version number, the author’s name, and sometimes even a title or opening heading.

For each reference give the following details: reference number; title (if it has one); author(s); version number and date of the version to which you referred; and location (where to find it). There are also extra things to say in some circumstances. These items are explained in more detail in the full version of this chapter.

Document History

Use the “Document History” section to record details of each version of the document. A version history is usually self-explanatory, but you can write an introductory sentence or two if you wish. It’s normally fine for the document history to reside within the document itself. But if the document is going to be (or might be) distributed outside the organization, consider maintaining the document history elsewhere. A document history is best presented as a table containing four columns: version number; when (typically the version’s release date); by whom (the name(s) of whoever made the change); and what changed.