Writing Requirements Specifications
It's been a long time since I drafted a Software Requirements Specifications (SRS) and I've definitely lost touch with some of those terms commonly used in a SRS. My own definitive guide to writing a good SRS is still IEEE Std 830-1998.
Here are some of the terms commonly used and their quality measures:
(Extracted from http://www.techwr-l.com/techwhirl/magazine/writing/softwarerequirementspecs.html)
|
Imperatives: Words and phrases that command the presence of some feature, function, or deliverable. They are listed below in decreasing order of strength. |
|
Shall |
Used to dictate the provision of a functional capability. |
|
Must or must not |
Most often used to establish performance requirement or constraints. |
|
Is required to |
Used as an imperative in SRS statements when written in passive voice. |
|
Are applicable |
Used to include, by reference, standards, or other documentation as an addition to the requirement being specified. |
|
Responsible for |
Used as an imperative in SRSs that are written for systems with pre-defined architectures. |
|
Will |
Used to cite things that the operational or development environment is to provide to the capability being specified. For example, The vehicle's exhaust system will power the ABC widget. |
|
Should |
Not used often as an imperative in SRS statements; however, when used, the SRS statement always reads weak. Avoid using Should in your SRSs. |
|
Continuances: Phrases that follow an imperative and introduce the specification of requirements at a lower level. There is a correlation with the frequency of use of continuances and SRS organization and structure, up to a point. Excessive use of continuances often indicates a very complex, detailed SRS. The continuances below are listed in decreasing order of use within NASA SRSs. Use continuances in your SRSs, but balance the frequency with the appropriate level of detail called for in the SRS.
1. Below:
2. As follows:
3. Following:
4. Listed:
5. In particular:
6. Support: |
|
Directives: Categories of words and phrases that indicate illustrative information within the SRS. A high ratio of total number of directives to total text line count appears to correlate with how precisely requirements are specified within the SRS. The directives below are listed in decreasing order of occurrence within NASA SRSs. Incorporate the use of directives in your SRSs.
1. Figure
2. Table
3. For example
4. Note |
|
Options: A category of words that provide latitude in satisfying the SRS statements that contain them. This category of words loosens the SRS, reduces the client's control over the final product, and allows for possible cost and schedule risks. You should avoid using them in your SRS. The options below are listed in the order they are found most often in NASA SRSs.
1. Can
2. May
3. Optionally |
|
Weak phrases: A category of clauses that can create uncertainty and multiple/subjective interpretation. The total number of weak phrases found in an SRS indicates the relative ambiguity and incompleteness of an SRS. The weak phrases below are listed alphabetically. |
|
adequate |
be able to |
easy |
provide for |
|
as a minimum |
be capable of |
effective |
timely |
|
as applicable |
but not limited to |
if possible |
tbd |
|
as appropriate |
capability of |
if practical |
|
|
at a minimum |
capability to |
normal |