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.

Review The Requirements

A formal review of the Software Requirements Specification (SRS) should be conducted prior to a major investment in the design or code. All of the many parties that have a stake in the success of a product should be involved in the review: users, marketing personnel, developers, testers, and so on. Everyone should be contributing to the correctness and completeness of the SRS.

Barry Boehm provides some advice on how to go about reviewing a SRS. In short, you want to determine if it is:

• complete
• consistent
• feasible
• testable

Related software development principles that can help with the SRS:

• Know Formal Methods
• Augment, Never Replace, Natural Language
• Write Natural Language Before a More Formal Model

Reference:
Boehm, B., "Verifying and Validating Software Requirements and Design Specifications," IEEE Software, January 1984.

Microservices

A well written article about microservices that doesn't subscribe to the buzz.

https://www.dwmkerr.com/the-death-of-microservice-madness-in-2018/

Identify Subsets

When writing a requirements specification it is important to clearly identify the minimal subset of requirements that might be useful. This is also known as identifying the minimum viable product. Now, extend that minimum viable product concept across the timeframe from when development starts and the completion of the product. Identify the minimal increments that might make the minimal subset more and more useful. Such identification provides software designers with insight into optimal software design. It will enable designers to:

1. More easily embed just one function per component.
2. Select architectures that are more contractible and extendable.
3. Understand how to reduce functionality in the case of a schedule or budget crunch.

A very effective technique of recording subsets is to rank the order of a products features by value. Compliment that ranking by grouping features into minimum viable products over the schedule of the product. Take your software requirements specification (SRS) and include columns in the margin beside each requirement. Each column corresponds to a different version of your product. These versions can represent multiple flavors of a product, each tailored to a different customer or situation, or they can represent increasing levels of enhancement through time. In either case, place an "X" in the appropriate columns to indicate which versions will have which features.

Reference:
Parnas, D., "Designing Software for Ease of Extension and Contraction," IEEE Transactions on Software Engineering, March 1979.

Record Why Requirements Were Included

A requirements specification is the culmination of many different activities: debates, discussions, architectural studies, statements of work, etc. So, when someone wants to change a requirement we need to know why that requirement exists - what was the motivation behind that requirement - before we can decide if it is safe to change it. Similarly, when a system fails to satisfy a requirement, we need to know the background of the requirement before we can decide if we should modify the system to meet it or modify the requirement to match the system. If your agile team is not giving any such consideration to missed acceptance criteria then your agile team needs to include the person writing the acceptance criteria.

When a requirements decision is made about an acceptance criteria, record a pointer to its origin. For example, if the decision was made during an interview with a customer, record the day and time, as well as the participants in the interview. It is only with such documentation that you can

1. evolve requirements later or
2. respond to situations where the as-built system fails to satisfy the requirements.

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