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.

Prototypes Reduce Risk In Selecting User Interfaces

To reach an agreement on a user interface prior to full-scale development, a prototype is your best choice for a low-risk, high-payoff approach. The simplest of prototypes would be a series of screen displays. These so-called "storyboards" give the users the impression of a real system. Not only do they help nail down requirements, they also win the hearts of the customers and users.


Reference:
Andriole, S., "Storyboard Prototyping for Requirements Verification," Large Scale Systems, 1987.

Determine The Requirements Now

Requirements are hard to understand and harder to specify. The wrong solution to this problem is to do a slipshod job of requirements specification, and rush ahead to design and code in the vain hope that:

1. Any system is better than no system.
2. The requirements will work themselves out sooner or later.
3. Or the designers will figure out what can be built as they are building it.

The right solution is to do whatever it takes to learn as many of the requirements as possible now.

• Do prototyping.
• Talk with more customers.
• Work with a customer to get to know his or her job firsthand.
• Collect data.
• Do whatever it takes.

Now document the requirements that you understand and plan to build a system to meet those requirements. If you expect requirements to change significantly, that's okay; plan to build incrementally (Grow Systems Incrementally), but that is no excuse for doing a poor job of requirements specification on any one increment.

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

Determine The Problem Before Writing Requirements

When faced with what they believe is a problem, many engineers rush into offering solutions. I am guilty of this myself - finding solutions and designing systems is an enjoyable activity. However, problems are often elusive. To properly define the problem:

1. Explore all alternative options for who really has the problem and what the problem really is.
2. Create several solutions for the perceived problem then explore the range of costs, risks, and time delay associated with each solution. While gathering these details you'll likely discover who really has the problem and why the problem really is.
• When solving the problem, don't be blinded by the potential excitement of the first solution.

"Procedural changes are always less expensive than system construction."

Reference:
Gause, D., and G. Weinberg, Are Your Lights On?, New York: Dorset House, 1990.

Poor Requirements Yield Poor Cost Estimates

Poor cost estimation can be traced back to these top five causes that all relate to the requirements process:

1. Frequent requirements changes
2. Missing requirements
3. Insufficient communication with users
4. Poor specification of requirements
5. Insufficient analysis

Here are some ways to improve your requirements process:

• Use prototyping to reduce the risk of incorrect requirements.
• Use configuration management to control change.
• Plan new requirements for future releases.
• Use more formal approaches for requirements analysis and specification.

Reference:
Lederer, A. and J. Prasad, "Nine Management Guidelines for Better Cost Estimating," Communications of the ACM, February 1992.

Take Responsibility

In all the [licensed] engineering disciples, when a design fails, the engineers are blamed. Thus, when a bridge collapses, we ask, "What did the engineers do wrong?" When software fails, the engineers are rarely blamed. If they are, the engineers respond with, "The error always existed. My change just exposed it," or "I was just following the pattern," or "My manager made me do it," or " The schedule left insufficient time to do it right." The fact is that the best methods can be utilized in any engineering discipline to produce awful designs. And the most antiquated methods can be utilized in any engineering discipline to produce elegant designs.

There are no excuses. If you are the developer of a system, it is your responsibility to do it right. Take that responsibility. Do it right, or don't do it at all.


Reference:
Hoare, C.A.R., "Software Engineering: A Keynote Address," IEEE 3rd International Conference on Software Engineering, 1978.

Research-Then-Transfer Doesn't Work

The achievements of software engineering research laboratories have difficulties making it into practice. Some reasons would be:

1. Software researchers have little experience developing real systems.
2. Solving a technical problem is easier than making sure it fits in a real system.
3. Researchers and practitioners have different vocabularies which results in difficult communication.

To best improve the chances of successful transfers, you need to from close ties between research and practice in the beginning. Use the industrial environment as the laboratory in which to germinate ideas. Don't try to formulate an idea then transfer it into industry.

Reference:
Basili, V., and J. Musa, "The Future Engineering of Software: A Management Perspective," IEEE Computer, Sept 1991.

Use The Same Name For The Same Concept

Technical documentation must always use the same words to refer to the same concept and the same sentence structure for similar messages. To do otherwise could confuse the reader, causing the reader to spend time trying to determine if there was a technical message in the rewording itself.

For example,

There are three types of special commands. Regular commands come in four varieties.

is not as good as:

There are three types of special commands. There are four types of regular commands.

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

Every Software Document Needs An Index

An index is a list of all terms and concepts used in the document, together with one or more page numbers where the term or concept is defined, used, or referenced. This is useful for requirements, design, test cases, and maintenance documents. The index is essential to finding information quickly and during maintenance.