Write Natural Language Before a More Formal Model

Augment, Never Replace, Natural Language says to create requirements specifications that contain both natural language and formal models. Let's go a step further: Always create the natural language version of a requirements specification first. If you write the formal model first, the tendency will be to write the natural language that describes the model instead of the desired system. This also applies to writing test cases. Write the test cases first to avoid the tendency to only test the code that was written or the way it is applied.

The best approach is to (1) write the natural language, (2) write the formal model, and (3) adapt the natural language to reduce ambiguities that become apparent when writing the formal model.

Augment, Never Replace, Natural Language

"In an effort to reduce ambiguity in requirements, software developers often decide to use a notation that is more precise than natural language. This is, of course, commendable in that ambiguity is reduced (Reduce Ambiguity in Requirements) by using finite state machines, predicate logic, Petri nets, statecharts, and the like. However, in such an effort, the specification is rendered less understandable by others (Keep the Requirements Specification Readable*) who may have less computer science or mathematical background than the requirements writer.

To alleviate this problem when using a formal notation, retain the natural language specification. In fact, one good idea is to keep the natural language and more formal specification side-by-side on opposing pages. Do a manual check between the two to verify conformity. The results will be that all readers can understand something and that some nonmathematical readers may learn something useful."


Reference:
Meyer, B., "On Formalism in Specifications," IEEE Software, January 1985.

Reduce Ambiguity in Requirements

Software requirements specifications are often written in a natural language. To reduce the ambiguity of natural language apply the following techniques:

1. Performing Fagan-type inspections on the Software Requirements Specification (SRS).
2. Constructing formal models of the requirements and rewriting the natural language as problems are found (Know Formal Methods).

Reference:
Davis, A., "Software Requirements: Objects, Functions, and States," Prentice Hall, Englewood Cliffs, 1993.

Separately Number Every Requirement

"It is essential that every requirement in the requirements specification be easily referenceable. This is necessary to enable later tracing to the requirements from the design (Trace Design to Requirements) and from test (Trace Tests to Requirements)."

I recently completed a project where there was not requirements specification document. The requirements were captured in a JIRA project. For anyone using a similar system for requirements tracking, the equivalent principle would be to make a ticket for every requirement. Don't get lazy and lump several requirements into one ticket just because they are related. If they are separate requirements then they need to be tracked as separate tickets.


Reference:
Gilb, T., "Principles of Software Engineering Management," Addison-Wesley, Reading, Mass, 1988.

Write Concisely

I often see requirements specifications with sentences like:

The target tracking function shall provide the capability to display the current tracking coordinates of all active targets.

Contrast this with:

When tracking, the system shall display the current positions of all active targets.

Organize Requirements Sensibly

Organize requirements in a way most natural for the customers, users, or marketing personnel. This will help avoid later changes or additions by improving understanding of what is being requested.


Reference:
Davis, A., "Software Requirements: Objects, Functions, and States," Prentice Hall, 1993.

Use Multiple Views of Requirements

Multiple views of requirements are needed to sufficiently understand or describe the behavior of a complex system. For example, you might use object-oriented analysis (OOA) to assess the real-world entities relevant to an application. OOA will help identify them and understand their interrelationships and attributes. You might use finite-state machines to describe the desired behavior. You might use decision trees to describe the system's behavior in response to complex input, and so on.


Reference:
Yeh, R., "Software Requirements: New Directions and Perspectives," Handbook of Software Engineering, New York. 1984.

Keep the Requirements Specification Readable

A requirements specification must be read and understood by a wide range of individuals and organizations: users, customers, marketing personnel, requirements writers, designers, testers, managers, and others. The document must be written in a manner that enables all these people to fully appreciate the system needed and being built so that there are no surprises.

Creation of multiple requirements specifications (each for a subset of the stakeholders) works only if you can guarantee consistency across the versions. A more effective method is to maintain the natural language (Augment, Never Replace, Natural Language) while incorporating multiple views of a more formal nature (Use Multiple Views of Requirements and Reduce Ambiguity in Requirements).

I want to stress the importance of keeping requirements specifications consistent. Many teams find it helpful to use a wiki, such as Confluence, to keep an easy to read and unified version of the requirements specification while using a ticket system, such as JIRA, to document the stories and technical tasks. If these two systems are not kept consistent then the project becomes much more difficult and understanding is lost.


Reference:
Davis, A., "Software Requirements: Objects, Functions, and States," Prentice Hall, Englewood Cliffs, 1993.

Use The Right Techniques

No requirements technique works for all applications. The requirements for complex applications can be best understood when multiple techniques are used. Use a technique or set of techniques most appropriate for your application.

For example, use entity-relation diagrams for data-intensive applications, finite state machines or statecharts for reactive (real-time) systems, Petri nets for applications with synchrony challenges, decision tables for decision-intensive applications, and so on.


Reference:
Davis, A., "A Comparison of Techniques for the Specification of External System Behavior," Communications of the ACM, September 1988.

Avoid Design in Requirements

The purpose of a software requirements specification (SRS) is to specify external behavior of the product. It should be specific enough that all stakeholders reach the same conclusion about the product's intended behavior. A different document created by a designer will specify a software architecture and/or algorithms.

If requirements writers (product managers) find it difficult to specify external behavior unambiguously without resorting to design, then a disclaimer should be included:

Warning: The "design" contained herein is supplied as an aid in understanding the product's external behavior only. The designer(s) may select any design they wish provided it behaves externally in a manner identical to the external behavior of the above system.

This is a good reminder to both the product manager that they are not the designer or architect, and to the designer that selection of optimal architectures and algorithms is their responsibility.


Reference:
Davis, A., Software Requirements: Objects, Functions, and States, Prentice Hall, 1993.