Guidelines for Writing Quality Requirements
(From Writing Quality Requirements by Karl Weigers, in the May 1999 issue of Software Development Magazine, from which the citation below is taken.)
There is no simple formula for writing excellent requirements. It is largely a matter of experience and learning from past requirements problems. Here are a few guidelines to keep in mind as you document software requirements.
- Keep sentences and paragraphs short. Use the active voice. Use proper grammar, spelling, and punctuation. Use terms consistently and define them in a glossary.
- To see if a requirement statement is sufficiently well-defined, read it from the developer’s perspective. Mentally add the phrase, “call me when you’re done” to the end of the requirement and see if that makes you nervous. In other words, would you need additional clarification from the SRS author to understand the requirement well enough to design and implement it? If so, elaborate on that requirement before you proceed. See Software Requirements Specification Checklist
- Requirement authors often struggle to find the right level of granularity. Avoid long narrative paragraphs that contain multiple requirements. Write individually testable requirements. If you can think of a small number of related tests to verify a requirement’s implementation, it’s probably written at the right level of detail. If you envision many different kinds of tests, perhaps several requirements have been lumped together and should be separated.
- Watch out for multiple requirements that have been aggregated into a single statement. Conjunctions like “and” and “or” in a requirement suggest that several requirements have been combined. Never use “and/or” or “etc.” in a requirement statement.
- Write requirements at a consistent level of detail throughout the document. I have seen requirements specifications that varied widely in their scope. For example, “A valid color code shall be R for red” and “A valid color code shall be G for green” might be split into separate requirements, while “The product shall respond to editing directives entered by voice” describes an entire subsystem, not a single functional requirement.
- Avoid stating requirements redundantly in the SRS. While including the same requirement in multiple places may make the document easier to read, it also makes it more difficult to maintain. You must update multiple instances of the requirement at the same time to avoid inconsistency.
See also: http://www.fowlersoftware.com/pages/ARTICLES.HTM
( Topic last updated: 2000.11.27 03:50:35 PM )