7 The Types of Specifications

There are a thousand ways to do something wrong, and a hundred ways to do it right. That definitely holds for writing requirements specifications. Don’t take the limited list presented here to mean that these are the only allowable document formats. Each company may have its own style of writing requirements documents. Below, we present descriptions of some common forms of requirements documentation.

7.1. User Stories (including epics and the like)

In general, a user needs to get things done. Very often, and especially in Agile projects, the first step in documenting a requirement is a “user story”. Generally, a user story will have the form “As a «role», I «want or need» to «action» so that «purpose».”. Here’s an example: “As a pilot, I need to know my altitude so that I don’t have unintended terrestrial contact.” Often, user stories leave out the purpose clause. Certainly user stories can have additional clauses and even be larger than one sentence. But, they’re usually kept short. The user stories relate to requirements documentation in that the user story is the basic indivisible quantity of requirement, often documented as a use case.

In Agile environments, user stories are often grouped into “epics”. An epic is a group of user stories which are related to one another and slated to be in the same release or set of sequential releases. A “theme” is a set of related epics. Recently, some people have begun to use “initiative” as a level between “epic” and “theme”. These groupings enter into the requirements documentation picture in that documentation is often done in an outline form, grouped by theme, initiative (possibly), epic, and user story.

7.2. Use Cases

A use case document is generally a document consisting of some introductory material, the cases, and any follow-on data, such as appendices.

More specifically, here’s what we tend to find in a use case formatted requirements document:

Title page: The title page goes here. For use in a class, any information required in your syllabus should be present, normally including the document title, your name, the assignment ID, the professor’s name, the class name, the section number, and the submission date. For commercial purposes, the list usually includes the project name, the company name, the customer’s name (internal or external), the document and/or product version number(s), and the authors’ names. For government-related documents, the title page (and other pages) will often have a classification level, such as Unclassified, Confidential, Secret, Top Secret, or other special-access notations as required, with certain rules regarding the size, placement, and color of those tags.

A note on version numbering (which applies to this type of requirements documents, other types of requirements documents, and products): Generally, the first version of something will be numbered 1 or 1.0, and subsequent start-from-scratch rewrites of documents will be numbered 2 or 2.0, 3 or 3.0, and so on. For products, products which have some incompatibility with previous versions will usually get “bumped” a whole version number. Document versions may or may not match product versions. Then they don’t match, there is usually text on the title page stating something on the order of “Document version __.__.__ for ______ version __.__.__”. When there is no rewrite involved, but a significant change or addition is being made, the second position of the version number will generally be increased. For instance, going from 1 or 1.0 to 1.1, from 1.1 to 1.2, and so on. When very minor changes are made and distributed, the last part of the version number will increase, for instance from 1 or 1.0 to 1.0.1 or 1.0A, depending on the style in use in that company, or from 1.0.1 or 1.0A to 1.0.2 or 1.0B. Note that if you’re bumping the third position past 1.0.9, the next version number will be 1.0.10, and not 1.1. If you’re bumping the second position past 1.9, the next version number will be 1.10, and not 2.0.

Revision history table: This is a table showing the distributed or published versions of the documentation. The first time the document is distributed, there should be one line in the table of versions. Each time the document is edited and then redistributed, a new line should be added to the table defining what has changed and why. When possible, this table should be on a single page, not split. If the table is more than one page, then the table should be the only thing on the pages it appears on.

Table of contents: Be sure that the table of contents accurately reflects the contents of your document. You don’t need to have everything in the document listed in the table on contents, in that if you have some section numbered 1.2.3.4.5, the table of contents might show the full list of section numbers, but might stop (for instance) at 3-part section numbers, showing 1.2.3, but not 1.2.3.1 or 1.2.3.1.1.

Note that when editing a requirements document other than the first version destined for distribution, you should edit in a manner that will show change bars. When editing subsequent versions, the change bars should show changes since the last distribution.

Editor hint: Various editors will let you mark section headers for inclusion into a table of contents and automatically produce the table for you. If you’re constructing a table of contents by hand, be sure to have a “decimal tab” or “right tab” separate the section description and the page numbers, so that the page numbers are right-aligned. The style of that tab should be set to dotted underline.

• §1: Introduction: Without getting formulaic, the introduction should state what the project is about. It’s also permissible to have the introduction area empty, and just use sections 1.1 and 1.2 as the introduction.
• §1.1: Purpose: This section should state the purpose of the application to be written. If the application is to be modified, then briefly recap the purpose of the application, and then get into the purpose of the addition or modification.
• §1.2: Scope: This area is generally a recap of the project’s charter — what the project can do to further the purpose, often involving budgetary and other constraints. This is the area that should, hopefully, prevent over-scoping, in that if it’s not in the definition of the project scope, then it shouldn’t be done.
• §1.3: Definitions, acronyms, and abbreviations: This section should include definitions of terms, and expansions of acronyms and abbreviations. If there is any chance that anyone reading the document will be unfamiliar with any of the terms, then those terms should appear in this section. Alternatively, each first use of a definition, acronym, or abbreviation can be defined inline the first time it’s used. The definition can appear after the first use (for instance, “This document is for the Example application (app).”) or the definition can appear after the (for instance, “This document is for the Example app (application).”). If this section is empty (either because there are no unique terms or because they’re all defined inline), you can leave this section out. But, pick a style and stick with it. Either define everything in this section, or define everything inline.
• §1.4: References: If you mention a document in the requirements specification document, then that outside document should be referenced in the reference section. References in this section should be in the appropriate as defined by your organization. For most places, especially schools, that’s the latest version of the APA (American Psychological Association) format guidelines, which is at the time of this writing, version 7. There should always be a reference or references back to the initiating document(s). For school assignments, this will typically be the assignment link. For other types of assignments, this will typically be an eMail, a purchase order (PO), some previous specification, or orders. If there is more than one document that the requirements specification is based on, then those should be listed, either individually, or as some higher-level collection of documents. So, this section should never be empty.
• §1.5: Overview: Often present as a set-up for the remainder of the document. If you refer to the document, use “this” and not “the”.
• §2: Overall description: This area would be an introduction to the product as a whole as it will be, or to the changes and/or additions that will occur. For a new product, this can be in the future or present tense (future preferred). For changes and/or additions to an existing product, any description of things as they are should be in the present tense, and any description of things as they will be should be in the future tense. This area doesn’t have to be long, but it doesn’t have to be short either. Don’t include actual requirements here.
• §2.1: Use case model survey: This is where the use cases are introduced. In one style (the most commonly used one), you’ll give a brief overall introduction to the list, and then the list, by name of the use case and brief description. That description can be a partial sentence (a phrase of a sentence with the subject and period missing), or one or more sentences. Don’t get long-winded here. You’re just introducing the list. On another style, the use case name will be listed with the one-sentence user story.
• §2.2: Assumptions and dependencies: In this section, list any assumptions and/or dependencies. Each assumption or dependency should be listed as a separate numbered, lettered, or bulleted item. If you have both assumptions and dependencies, don’t intermix them, list all assumptions (or dependencies) before going on to the other category. There should be no requirements in this section either.
• §3: Specific requirements: Here is where the requirements proper start. Sometimes this section has text in it, and sometimes not. This section should start on a new page if it does not have text in it. (You’ll see why shortly.)
• §3.1: Use case reports: This is where the use cases start. Again, sometimes this section has text in it before the first use case report, and sometimes not. If §3 and this section have no text of their own, then §3 should start on a new page. If §3 has text and this section has no text before the first use case, then this section should start on a new page. Within this section there will be one or more use case reports.

Each use case report: Each use case report should have a title that matches the title of the use case in the listing above. The use case reports should be in the same order as the use case list. Each use case report should be numbered (1, 2, 3), lettered (A, B, C), or numbered as subsections (3.1.1, 3.1.2, 3.1.3). Within each use case report, there should be these other items:

Summary: This section should summarize the case in plan English.

Preconditions: This section should be a list of the preconditions, if any, for this step to begin.

Triggers: This section should be a list of the triggers (normally and at least one) that start this flow.

The basic flow of events for user interaction scenarios and for sensor-interaction scenarios: This should be a table, with a header and one or more following rows. The heading items should be “Actor” (or some similar word), “System” (or something similar), and “Screen” (or whatever is most appropriate). There should be one step per row, or one pair of actor and system steps per row. The steps should be numbered, starting with 1 for the actor, and normally 2 for the system. On the first row, there should be a picture of the screen, a drawing of the screen, or a description of the screen. In subsequent rows, a new screen picture or description should appear when there are significant changes to the screen. That’s assuming that this functional area has a screen. Leave out the third column if not. Don’t use the term “actor” within the “Actor” column. If you have just one class of user, use “user”. But, if you have more than one class of actor, use the class name, such as “customer” or “administrator”. Sometimes, the system will be taking its input from sensors instead of people. For instance, an elevator door uses a light beam and a photocell. When someone breaks the beam, the doors retract if they’re closing, and the “close” timer resets. In this sort of case, “sensor” or the like is what goes in the Actor column. If you intermix use actions with sensor actions, there should be a “Screen” column. If you have only sensor interactions (autonomous functionality) with no displayed output, then there should be no Screen column.

The basic flow of events for conditional scenarios: If actions take place because of conditions alone, the “Actor” column should be replaced by a “Condition” column. Back to the elevator example, a condition might be that the doors are open, and it’s been 5 seconds since the “Door Open” (or “«»”) button was pushed or the beam was broken. The system response would be to close the doors. Again, if there’s no display associated with this autonomous action, there should be no screen column.

Alternate flows of events: When there is an alternate flow of events, this should appear, much in the same format as above, but starting at the first divergent step.

Post-conditions: If there are any changes as a result of the primary or alternate flows to the permanent state of the system (or the outside world) or to the state of the session, then those changes should be listed as post-conditions.

Each use case report should be on its own page, with two exceptions: (1) For the very first use case report, if the §3.1 header had no text of its own, don’t start a new page, because that would cause you to have a page with one section header line on it. (2) If two use case reports will fit entirely on one page with each other, do so.

• 3.2: Supplementary requirements: If there are any system-wide requirements or so-called nonfunctional requirements, those should be listed here.
• 4: Supporting information: Any additional information (not requirements) should go in this section.

Diagrams: Sometimes, one or more diagrams is required, most often some sort of UML diagram. Those diagrams can go into the Supporting Information section, or into some other section, or into an added section. The general rule is that the diagram(s) should appear where they would first be useful. (We have a separate section on UML diagrams in a much later section.)

Sheldon’s advice: Use UML diagrams and other diagrams only when they add in understanding, or when the boss or customer requires them.

If you have nothing for a given section that has no subjections, either use “Not applicable”, use “N/A”, or leave the section out, renumbering the other sections as necessary. If you have nothing for a given section that has subjections, such as having nothing to say between the §3 header and the §3.1 header, that’s ok. Don’t leave §3 out or claim that §3 is not applicable. If a given section has only one subsection, then combine that subsection with the enclosing section.

A complete template appears as Appendix A, and a complete example appears as Appendix B. In Appendix A, blue areas are notes, not to be included in the final document, and fields marked with angle brackets (“<” and “>”) are items that should be replaced with your text. The angle brackets should not appear in the final document.

7.3. APIs, Connectors, and other Black-box Techniques

Sometimes you need a system that, given certain inputs, produces certain outputs. If everything the system does can be described in terms of its inputs and outputs, then the system can be described by an interface, or API, description or documentation alone. In those cases, an API reference is written, and the software can use that API reference as a specification. When the functionality of a hardware or hardware-and-software system can be described in this manner, the unit is often called a “black box”. (Notes: The term “black box” is also used in testing and in aircraft. In testing, it means that the testers don’t get to see the inside of the equipment or the code. In aircraft, it means the flight recorder, even though it’s dayglow orange. “White box” testing means that QA does get to see the insides and code.)

7.4. IEEE 830 and the Like

In circumstances where the organization or the customer wants complete documentation on everything, especially in aerospace and military projects, IEEE 830 format or some MilSpec (Military Specification) format is used. Generally, you’ll have these sections in an IEEE 830 document:

Title page, table of contents, and revision history (or table of versions) are the same as for the Use Case document.

• §1 Introduction should be a title only.
• §1.1 Purpose should be the same as in the Use Case format.
• §1.2 Document convention should tell us anything special about the typography, such as bold meaning a certain thing, color meaning a certain thing, special symbology, or the like. It’s ok to have this section as “N/A”.
• §1.3 Intended audience and reading suggestions should tell who the intended audience for the document is, and give reading suggestions. For instance, if project management and developers need to read the whole document, but the QA staff only needs to read certain sections, mention that.
• §1.4 Product scope and §1.5 References are the same as in the Use Case format.
• §2 Overall description has no text of its own, but is only used to hold subsections.
• §2.1 Product perspective typically introduces why this product or version is being produced, including who the intended users are.
• §2.2 Product features gives a brief introduction to the product’s features, including a list of the features’ names.
• §2.3 Use classes and characteristics gives us a list of the user classes, what’s different about one user class from another, and what features apply to each class. On some projects, there is only one class of users, and this section may only be one sentence long. On more complex systems, there may be dozens of user classes, with a table showing which of the thousand features can be used by the dozens of user classes.
• §2.4 Operating environment tells us what the intended operating environment is. For hardware, this might entail temperatures or connection to a type of electrical buss. For programs, it might tell us about a cloud system or an operating system or the like. Don’t use this section to make decisions for the project manager. This section should only be used to describe existent facts or planned operations. For instance, tell us if there is an existing Unix system that the new components need to be added to, but don’t tell us that the system should be written for Unix if there is any way that the system could work outside of a Unix environment. If there is some reason that you need to limit the project manager’s choice, in this section or any other section, give a reason. Each specific environmental concern should be in a separate paragraph and have an ID, “OE-” and a number, such as “OE-1”.
• §2.5 Design and implementation constraints is another section that follows almost the same rules. The design and implementation constraints should optimally be “N/A”, leaving all the decisions to the project manager. But if there are constraints required, list them here, with the first design constraint labeled “DC-1” and the first implementation constraint labeled “IC-1”.
• §2.6 User documentation should list the existing and required documentation. Each entry should state implicitly or explicitly whether the documentation already exists. How to do explicit statements is obvious. Implicit statements should use “is” or “shall be” to indicate existing and future documentation, respectively. If something already exists and must be modified, that needs to be stated explicitly.
• §2.7 Assumptions and dependencies is as per the Use Case documentation, except that the assumptions should be labeled with “AS-1” and on, and the dependencies should be labeled with “DE-1” and on.

Before we go on, it must be stated that the idea in this type of documentation is to define things, and then to use that definition to build requirements on. §3 expands on the list from §2.2, and serves as the basis for §4 and §5. Within §5, each stimulus-and-response pair will serve as the basis for the actual requirements.

• §3 System features serves as the introduction for the list of product features. There is usually an introductory paragraph. This section contains subsections numbered 3.1 and on, each with a title that matches a feature name, and a brief description, most often one sentence long, but sometimes as many as three.
• §4 External interface requirements is solely a section header, with no text of its own.
• §4.1 User interface overview is just that. It describes the user interface’s guiding principles. It may contain pictures, but might not. The entire user interface can be described (and thus required) here, or that can wait until §5.
• §4.2 Hardware interfaces describes how the software interfaces with hardware, or how hardware interfaces with other hardware. This section may be broken down into subsections, so that each functional area’s interfaces can be described one at a time.
• §4.3 Software interfaces describes how software interacts with other software. If the interaction is internal and can be handled as a “black box” system, don’t describe those interfaces any more tightly than you have to. If the software is to interface with the outside world, or with another system, or with a component to be built by another company or entirely separate group, then that interface should be described in detail here.
• §5 System Features/Modules: This section may have an introductory paragraph, but mainly it holds one requirements block per functional area. These functional areas will be numbered starting with 5.1, and the list of functional areas should match the earlier list. Within each such area, you’ll have these subsections:
  • §5.__.1 Description and priority: The description is a plain English description of what the module does, and why, in as much detail as you can provide. The priority can be in the form of High, Medium, and Low. Some even add Emergency and Possible. Alternatively, the priorities can be ordinal, such as first, second, and so on, or ordinary, such as 1, 2, and so on. Priorities can also be in the form of Due By dates.
  • §5.__.2 Stimulus/Response Sequences: This section should have the stimuli that make things happen (usually, in order, a user input or a sensor report), and the system’s response to each stimulus, labeled “Stimulus” and “Response”. In the case of a clock going off, rather than using Stimulus and Response, use Condition and Response. If all the items are conditions and responses, relabel the area to “Condition/Response Sequences”.
  • §5.__.3 Functional Requirements: This section first echoes each stimulus/response (S/R) pair (or C/R) as a requirement, in “Upon «stimulus or condition», the «component» «shall or must» «response»” form. Following the echoed requirements, and additional requirements for the area not specifically based on a stimulus (if any) should be listed. Each requirement should have an ID of REQ-__.__, such as REQ-1.1, where the first number matches the center number of the 5.__.3 section, and the second number starting with 1 for each group.
• §6 Nonfunctional Requirements: This section lists nonfunctional requirements, as defined above. Often, these nonfunctional requirements are grouped into subsections, such as Performance, Security, and the like. There should almost always be performance requirements. Typically for user interface items, anything the user does should have an immediate visible effect, such as a button going into a “depressed” or “disabled” state, or changing name, and/or the cursor changing to a “watch” cursor. When possible, operations taking longer than 2 seconds should show a progress bar. For aircraft, the standard is that when the command is accepted but the situation doesn’t match the command yet, the indicator should be blue. (For instance, we have a fuel valve which we can control, so the value has a white “controllable” indicator, and we do some action that’s supposed to close the value. The control should redraw [assuming it’s a drawn control] to the closed position, and the indicator should turn from white to blue to show that the action has not occurred. As soon as the action has occurred, the indicator should return to white.) If some action will take some time to perform, but is not something the user needs to wait for (such as starting a print job), there should be some briefly visible indication that the process has been started. All nonfunctional requirements should be measurable. For instance, it’s not ok to say that the system will support a lot of users with no performance degradation. It is ok to say that the system must be able to support 1,000 users with the average response time under 500ms. The first is no ok, because we can’t measure what “a lot” is, nor can we ever measure “no performance degradation”, because we don’t know how many “a lot” is, and because as soon as you get the second user, there is some performance degradation. The second requirement is much better, because we know how many users 1,000 is, and we know how much time 500ms is, and we can run a test with 1,000 loads and measure the average response time.

A template and sample appear at the end of this document as Appendices C and D, respectively. Appendix E gives an example of how a lightswitch might be specified for §5 in this style of documentation.

7.5. Manuals as Specifications

In many circumstances, a manual for a new product or software library or device can serve as a specification for that project. Manuals are much cheaper to produce than software, and to the average stakeholder, easier to understand than the typical requirements document. Also, stakeholders tend to be happy to receive specifications in the form of a manual, because it makes them feel that a lot of progress is being made. However, when doing a manual as specifications, make sure that they understand that the product is not complete at that point.

7.6. Pure R&D

When doing pure research, or research and development, rather than just development, almost by definition, you don’t know what you’re going to get. In the pure research case, one would expect that the specifications hold only guidance on what type of research is to be done. In pure research and development, the end goal is known, but little will be said about how those goals are to be carried out. For instance, when President Kennedy said that the US would go to the moon within the decade, he didn’t say it was going to be a 3-man crew with a separate lander. (The original plan was for two Saturn Vs to put up and assemble a spacecraft that would land on the moon and return.) What’s often called R&D is really pure development, in that the final result and design is either fully or mostly known.

7.7. How Things Can Go Wrong

This one is pretty easy. Any complete specification that the customer (or internal team) is happy with is a hit. The only problem that can arise here is that if the customer demands one type of specification, and you deliver another type, you may have to do it over. Often, government and safety-related projects will demand a certain format.

7.8. Discussion Questions

1. It’s not the case that you must do your work in exactly one of these formats. When doing your work, do you have an affinity for one of these formats? If so, which and why?
2. If not, do you see things from any of these formats that you think is pretty good?
3. Or things you think should be avoided?