Fix Requirements Specification Errors Now

Errors in the requirements specification will cost you:

• 5 times more to find and fix if they remain until design.
• 10 times more if they remain until coding.
• 20 times more if they remain until unit testing.
• 200 times more if they remain until delivery.

That is more than convincing evidence to fix them during the requirements phase!

Start using your software architects and key software engineers to review software requirements before they go to development. Don't do this as a waterfall process where the SRS goes from Product to Architecture to Development. Make it an agile process where people get involved before the SRS is "done." It will make changes easier and less painful.

PROTIP: Put the SRS in a version-control system such as GIT with each section a separate file. This way anyone can make changes to the SRS that can be reviewed, approved, and tracked. Add in a script to combine the sections into a single file for easy handling. Everyone knows that this can be done but I have yet to meet a single product management team that does it.

Reference:
Boehm, B., "Software Engineering," IEEE Transactions on Computers, December 1976.

Top 10 Project Management Risks

As a software architect, I've assisted in project management and filled the role of product owner. For all of these roles it is important to be familiar with the situations that most often cause software disasters. These are your most likely risks, but not all of them:

• Personnel shortfalls
• Unrealistic schedules
• Not understanding the requirements
• Building a poor user interface
• Trying to gold-plate when the customer doesn't want it
• Not controlling requirements changes
• Shortfalls of reusable, interfaced components, or microservices
• Shortfalls in externally performed tasks
• Poor response time
• Attempting to exceed the capability of current computer technology

If you don't already have one, this list is a good starting point for a project planning checklist. Additionally, you should add risks unique to your environment, industry, and project then develop plans on how to mitigate them.

Reference:

Boehm, B., "Software Risks Management: Principles and Practices," IEEE Software, January 1991.

Quantify Requirements

All to often terms such as "fast," "responsive," and "extensible" are listed as software product requirements. Software architects often spend a lot of time helping product owners turn these desires into objective requirements. We do this by asking a lot of questions: How often? How many in what period? Increasing or decreasing at what rate?

It is a process that most product owners find maddening. Which is why it is important to explain that an exact answer is not expected. In fact, an exact answer would be a little worrying and I'd want to know how they got it. It is that process of how to get quantitative criteria that often needs to be explained and planned for. Finding ranges for quantitative requirements and checking against them is a time-consuming and expensive process. If no one wants to spend the time, effort, and money to do so then it reveals that the requirement isn't actually needed.

Focus your efforts on the parts of the system that stakeholders actually consider worth paying for.

Plan A Project In Detail

Every software project needs a plan. The level of detail should be appropriate for the size and complexity of the project. At an absolute minimum, you will need:

• A PERT chart showing the interdependencies among tasks.
• A GANTT chart showing when activity will be underway on each task.
• A list of realistic milestones (based on previous projects).
• A set of standards for writing documentation and code.
• An allocation of people to various tasks.

As projects increase in complexity, each of these requirements becomes more detailed and more complex, and other documentation becomes necessary. A project without a plan is out of control before it even starts. As the Cheshire Cat said to Alice in Wonderland, "If you don't know where you are going, any road will get you there!"

Reference:

Glaser, G., "Managing Projects in the Computer Industry," IEEE Computer, October 1984.

Provide All The Information The User Needs And Nothing More

A key part of the design process is the precise definition of each and every software component in the system. This specification will become the "public" part of the component. It must include everything a user needs, such as its purpose, its name, its method of invocation, and details of how it communicates with its environment. Anything that the user does not need should be specifically excluded. In most cases, the algorithms and internal data structures used should be excluded. For if these were "visible," users might utilize this information. Subsequent enhancement or modification then becomes profoundly more difficult because any change to the component has a cascading effect on all components that use it (related to encapsulation).


Reference:
Parnas, D., "A Technique for Software Module Specification with Examples," CACM (May 1972).

Store Requirements in a Database

Keep in mind that the follow quote is from 1995. It is still completely relevant.

Requirements are complex and highly volatile. For these reasons, storing them in electronic media, preferably a database, is a good idea. This will facilitate making changes, finding implications of changes, recording attributes of specific requirements, and so on.
      Some of the things you want to store in the database are unique identifier (Separately Number Every Requirement), the text of the requirement, its relationship to other requirements (such as more abstract or more detailed descriptions of the requirement), importance (Prioritize Requirements), expected volatility, pointers to its sources (Record Why Requirements Were Included), applicable product versions (Identify Subsets and Give Every Intermediate Product a Name and Version*), and so on. Ideally, the requirements specification itself is nothing but an organized "dump" of the entire database.

I have used JIRA. There are many tools like it. They can do all of the above, but it is up to the person creating a ticket in JIRA to ensure those things are done. I think they are really important so I'm going to list them again.

• Create the ticket in a backlog or project that is unique. Do not lump unrelated tickets together. This will result in a "fatlog" - a fat backlog that is difficult to groom and manage.
• The text of the requirement goes in the "description". The "summary" is not where the requirement should be detailed. Personally, I think systems like JIRA should not allow tickets that have no description to be saved. Engineers should refuse to estimate such tickets and Product Owners who create them should be ashamed.
• JIRA has a feature to link tickets. Use it. If there is a dependency then utilize the sub-task feature. Make a story that encapsulates both tickets and make them linked sub-tasks. Use the system to track if everything for that requirement is actually done.
• Order the tickets by importance. There can only be one highest priority and it at the top.
• Use comments to document the sources/stakeholders for a ticket. Do not use comments to have a discussion about a ticket. Email, call, instance message, etc with the people involved. If you absolutely must use the comments section of a ticket to have a discussion then clean it up later. Delete anything that will mislead people reading the ticket. If you want to save the history then move that stuff into a document and attach it to the ticket with a title that makes it clear that it is for history and it is not the requirement. The actual requirement is in the description.
• Ensure that you put what product the ticket applies to either in the summary or the description. You might be inclined to think that it is clear by where the ticket sits. For example, the ticket is in the product A backlog. Invariability, someone is going to get confused and try to work that ticket for product C which is really similar to product A. I've also seen people accidentally move a ticket to a different backlog then not be able to figure out where it belonged.
• If you can't take the issues in a JIRA backlog and print them out in order and call that your software requirements specification (SRS) then your backlog is a mess and you have some work todo.

6 Tips to Make Your Backlog Lean

Self-Destruct TBDs

A software requirements specification (SRS) with a TODO or TBD (To Be Determined) note is obviously not complete. There may be good reasons for approving and starting work on a project with a TBDs in the specification. This is particularly true for requirements whose precision are not critical to fundamental design decisions.

When you create a TBD, be sure to footnote it with a "self-destruction note," that is, specify who will resolve the TBD and by when.


Reference:
IEEE, ANSI/IEEE Guide to Software Requirements Specifications, IEEE Computer Society Press, Washington, DC, 1994.

Specify When Environment Violates "Acceptable" Behavior

Requirements specifications often define characteristics of the system's environment. This information is used in making intelligent design decisions. It also often implies that the developer is contractually obligated to accommodate such characteristics. What happens after deployment when the environment exceeds the specified limits?

Suppose the requirements for an air traffic controller system specify that the system shall handle up to 100 aircraft in a sector simultaneously. They system is built and correctly satisfies this requirement. Three years later 101 aircraft accidentally enter a sector. What should the software do? The possibilities are:

1. Print an error message.
2. Crash.
3. Ignore the 101st aircraft.
4. Process all 101 aircraft but perhaps not satisfy some other timing constraint (such as how often the screen is updated).

Obviously, options 1, 2, and 3 are unacceptable. Yet they are valid system responses as (not) stated in the requirements. The right solution is to explicitly state in the software requirements specification (SRS) the expected system response when the environment exceeds any of the constraints defined for it.


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

Specify Reliability Specifically

Software reliability is difficult to specify. Don't make the problem even more difficult by being vague. For example, "The system shall be 99.999% reliable" means nothing.

Does it mean that the system cannot be "down" more often than 5 minutes every year but that it is okay to occasionally make a mistake (for example, a hotel reservation service may occasionally mix up hotel details). Or does it mean that it must make no more than one mistake every 100,000 transactions (for instance, a patient monitoring system cannot cause the death of more than one out of every 100,000 patients)?

When writing requirements, differentiate between:

1. Failure on demand.
•  What is the likelihood, measured as a percentage of requests, that the system will fail to respond correctly? For example, "The system shall correctly display 99.999% of hotel information."
  
2. Rate of failure.
•  This is the same as "failure on demand" but it is measured as a percentage of time. For example, "The system may fail to report hotel information correctly no more than twice a year."
3. Availability.
•  What percentage of time may the system be unavailable for use? For example, "The hotel reservation system shall be available 99.99% of the time in any given calendar year."

Reference:
Sommerville, I., "Software Engineering," Addison-Wesley, Reading, MA, 1992.

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.

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.