Requirements specification for writing a requirements specification (excerpt)

Use cases

Primary actor

Author

Stakeholders

Developer
Tester
Documentation specialist
End user
Technical support

Preconditions

The Author is expected to be omniscient and inerrant with regard to the problem domain.

Primary flow

1. Author estimates how long it will take to write the specification, a number usually extracted from the anterior portion of Author’s digestive tract.
2. Author analyzes and documents the feature in English, a different language than that used in the subsequent implementation.
3. All stakeholders review and eventually sign off on the specification, without paying attention to what it actually says. Much time is spent correcting the use of “shall” and “may”.
4. Developer ignores the specification, and implements the feature “the way it should work.”
5. Tester painstakingly constructs tests for every requirement in the specification, including the eventuality of a Category 5 hurricane.
6. Most of those tests fail, to the secret glee of Developer — who suggests that the specification be modified.
7. Author duly modifies the specification based on a misunderstanding of the implementation.
8. Documentation specialist documents the feature based on a misinterpretation of the original version of the specification.
9. Author and Developer review the documentation, ignoring those errors. They each suggest numerous, conflicting modifications to correctly paint the important role played by their chosen framework.
10. End user discovers a problem with the feature and calls Technical support.
11. Technical support informs End user that the supposed “bug” is actually part of the design, and is in fact a highly valued feature provided by the chosen framework. Technical support takes every pain to politely insure that End user is fully aware of his/her own ignorance in this matter.

Alternate flows

4. Developer worships the specification, and slavishly implements the feature according to the letter thereof — especially its mistakes.
8. Documentation specialist becomes aware of modified specification, and adjusts the documentation to misinterpret the newer version.
10. End user discovers a problem, but doesn’t bother to call Technical support because he/she has already had his/her self-esteem sufficiently lowered by his/her boss that day.

Exceptions

Author and Developer understand each other completely, all tests pass, Documentation specialist’s interpretation nails the specification and behavior, and the End user is happy with the feature. This is an unlikely scenario, but should be documented here in order to insure that it is prevented.

Specific Requirements

1. Author

1.1 Author shall gather all use cases and exceptions for the feature prior to writing any code.

1.1.1 Omission of any use case or feature shall throw an AuthorOmniscienceFailureException.

1.2 Author shall provide an accurate estimate of the time required to write the specification.

1.2.1 Failure to meet or beat this estimate shall trigger an analysis of Author’s failings. Depending on the determined source of failure, one of the following exceptions shall be thrown: ExcessiveWorldofWarcraftException, InterviewingFrequencyException, BlogOverflowException, or the more general LazyAssAuthorException.

(etc.)