Software Engineering
Home Planning Requirements Writing Hazard Analysis Requirement Analysis Config Control Software Design Software Testing Software Standards Basic Logic

Requirements Writing - Specification, or Implementation?

From Practical Software Requirements. Kovitz, Benjamin L. Manning. 1999.

The IEEE glossary of software terms defines "Specification" as a document that describes requirements. So technically, a "Specification" is a collection of Requirements.

A Requirements Specification describes the behavior of the system from the problem domain’s perspective.

A Requirements Specification does NOT describe how to implement the system in the machine domain!

Requirements can be written in natural language or formal language. Natural language has the advantage of being readable by all parties, but the disadvantage of being somewhat vague and imprecise. Formal language has the advantage of being precise, but the disadvantage of requiring special knowledge to read and understand the requirements. Formal language is primarily intended for use in design architecture and design description documents, rather than in software requirements specifications.

True Horror Story

If a customer is asked "what do you need?" they will generally reply with an implementation that they have envisioned - not with the actual business need.

I was visiting a jail in a major U.S. city while gathering requirements for their jail management software. We were replacing an older system, whose requirements gathering had begun with "We need a database to..." Their vendor had been asked for a database, and they wrote a great database. Unfortunately, it did not match the jail's workflow. The result was roughly a threefold increase in the prisoner escape rate! The increase was entirely attributable to the vendor's inability to automate the jail's actual workflow, which had forced the jail to change their workflow to match the software.

Requirements also exist at two levels of detail:

  • Business Needs. These are the needs as expressed by the user. These will be too vague to write software, but they provide the rationale behind the detailed requirements. These should only be written in natural language, since they must be understood by everyone on the project. For the jail management system in the story above, we watched their workflow for two days, asking questions and collecting examples of forms. At the end of the visit, we fully understood their real workflow needs.
     
  • Software Requirements Specification (SRS). These are the detailed requirements that describe the system. These should primarily use natural language, and use formal language where only where the precision is useful.

Requirements also decompose in a hierarchy (yuk!): One Business Need generates one or more Requirements (one-to-many = good!). A Requirement should not derive from more than one Business Need (many-to-many = bad!). General guidelines to remember are:

  • One Business Need creates one or more Software Requirements (one-to-many).
  • Through Requirements Analysis, one Software Requirement creates one or more Test Objectives (one-to-many).
  • One Test Objective creates one or more Test Steps (one-to-many). Alternately, one Test Step may instead cover one or more Test Objectives (many-to-one).