The problem you face in writing specifications is that it doesn't seem to have an obvious payoff. It is easy to write up something that covers the ground but misses important points. The information below examines the eight points of specification and gives background for how and why they should be entered.
Requirements and Specifications form the basis for the Design Document(DD). This is the point where the RSD process starts to pay off because the DD is the critical first step in creating a reliable, long lived application. Any information that is missing or incomplete when the DD is created can have a large impact on the cost and success of the whole project. Studies have confirmed that the most expensive errors to fix are those which are missing or wrong in the specifications. The reason for this fact will become clearer when you understand how entropy affects program costs, and how the DD enables you to keep entropy from destroying systems as they age.
Specification, as I wrote earlier, deals with the How of the product. How means several things in two classes:
System Specifications:
Operational Specifications
The Human Interface (HI), often called user interface, is one of the toughest parts to specify. Because we refer to them as users, we tend to forget they have fallible human characteristics. Each environment and set of humans has different backgrounds and expectations. The best way to start is by dividing the HI into logical steps, ignoring the layout. The HI design will need to be tuned with input and experience from the people who will use the system. The important part of HI specification is to clearly state what information needs to be conveyed to the people, and what information is returned by them. For example, 'Display item order number, description, availability and price, enter numeric quantity wanted' on a sales order form.
To specify the control flow, you can break the functions into independent steps, each accomplishing one unit of work. A unit can be assembled by working with logically related data items, such as name, address and phone number. That unit would include a postal code, but not a list of hobbies. Units should be small and only include closely related items. Control flow then ties the appropriate units together in steps to accomplish the intended function. Calculations and text processing should also be specified with each unit.
This is also the time to identify the sources and sinks of the data elements. One potential problem is that older systems used less stringent filters for data. This can cause problems for new systems which assume 100% accuracy. Even if you don't have a formal data repository, now is the time to specify accuracy and range for each data element. This will probably be an enlightening process as most systems haven't considered this in detail.
Reliability is often discussed in terms of the hardware and operating system, yet usually ignored in application systems. People tend to assume that applications should be 100% reliable, and anything else is a bug. That's actually too narrow a view of reliability for best design. Perfect reliability has the hidden assumption that people, including the designers, are perfect. It is a certainty that some of the data elements will have outliers, values beyond the expected ranges, and it is a certainty that people will enter a wrong value.
A reliable system must detect these errors as early as possible in processing and allow immediate correction or deferred correction. You should match the cost of detection & correction with the cost of the error to judge if one can be ignored. Handling every possible error may be ideal, but it could be too costly.
Critical errors are those which are expensive in impact or create a cascade of errors effect. These may also include problems internal to the programs, such as crashes or creating bad records. Depending on potential costs or customer impact, it may be necessary to create checkpoint files, recovery methods and data filters to insure reliability. This is the time to specify what a critical error is and how it is to be handled, and the costs of not handling it.
Security includes control over who uses the system and how tightly the whole system is protected. Access control is the main part of this, but don't forget that there are other ways to access data files than the applications you are planning. Every OS has utility programs to copy or examine files, plus there are many potential security holes in all but the most secure military systems. For a very few areas, such as potential acquisition candidates, major new product development and other 'bet the company' work, a totally isolated computer system or a high level of encryption and secure identification may be needed. It's not a comforting statistic to know that more than two-thirds of company security breaks are from inside.
The job of the Design Document is to cluster groups of data elements, their sources, sinks and the data flow into a system design. The DD identifies how the programs and files interact in the system. This is where you partition the system into individual files and programs to meet the functional requirements.
At this point, the question of sequential or random file or SQL table can distract you from the critical issue of interactions. The interactions in a system design are between user and function, function and program, program and file, and between the programs. The number and kinds of interactions between the components of a design will be a major factor in how difficult it is to build, maintain and enhance.
There is a direct analogy between the interactions in a system design and what is called 'Coupling' in a program. If two parts of a program each depend on details of the other part, it is called 'Tight Coupling'. If they only exchange data through an interface that is independent of those details, it is called 'Loose Coupling'. When you add enhancements, as inevitably happens, tight coupling means you have to change both parts together. Loose coupling means you only have to change one at a time. The difference in effort is not a linear function of the work involved, but at least quadratic. Coupling can be considered a measure of disorder in a program or a system. Entropy is the word used to describe the disorder in a physical system. It also can be applied to software.
Entropy is a measure of disorder, and by the first law of thermodynamics, entropy will always increase. Any local decrease requires work, which itself increases entropy elsewhere more than the decrease the work creates. The laws of thermodynamics are obscure until translated into English:
One of the objectives of the DD is to minimize coupling, and where it is necessary, identify the required interface. The reason for this is to make future changes and additions to the system simpler in order to limit the increase of interactions or system entropy. This concept of entropy can be demonstrated by a hypothetical example.
Let's start with a new system, just installed and amazingly, free from bugs. It is at this point the system is at a state of minimum entropy. It has the fewest interactions it will ever have without starting over from scratch. When (not if) the first enhancement is added, programmers go to work to make changes. If you are lucky, some of the original programmers will still be available. If you are very lucky, they will start by examining the changes needed at the DD level to determine how to minimize interactions. Programmers, being all too human, tend to jump into the obvious program and start changing code.
What happens now is quite predictable. In a rush to get done, the changes are made in the easiest way, debugged quickly and the system tested. Entropy has already increased by the addition of the changes. The faster the changes go in, the less design time spent, the more entropy will increase. The next mistake usually made is skipping the Quality Assurance testing and moving the revised system into production. It's been debugged, right?
Not exactly.
Now when bugs are discovered, they must be fixed ASAP because it is a production system and delay is painful if not costly. The hidden cost in all of this is the entropy of the system, its measure of disorder, has increased with every change and every bug fix. Entropy is invisible and lurks in wait for the next round of enhancements. Every time a bug is fixed or an enhancement added, it takes longer, costs more and further increases entropy. Eventually, the disorder (entropy) exceeds the ability of the programmers to handle and the system becomes unmaintainable. Entropy has disordered the system to death.
The DD is a graphical representation of how the files and programs work as a system. The challenge to the design group is to find the best partitioning of the programs and data files to meet the goal. The easy route to the DD is to collect the obvious groups of functions into programs, define the files for those programs and draw up a DD which ties them together. Too often this is where it stops.
The easy route is but a first step to finding a good design. It typically aggregates too many functions into a single program and file. As a first step it is okay, but don't stop there. Next, the designers should divide the files and programs into their smallest reasonable pieces and lay out a new DD that collects all the pieces into a system. The purpose of this step is to force the designers to look at each piece of the puzzle in detail. It will become much clearer which elements of the data must be together, and which functions collect into a minimal program.
Now you can build the third DD, using what was discovered in the second. This will be closer to optimum than either the first or second. In some cases all that you need to finish is some fine tuning. In more complex systems there may be more work to find the best DD. When you create the first DD, there can be two mutually exclusive ways of partitioning the system, with no clear best design. In this case you should carry both designs through to the third DD. The process of separation and reassembly will make the choice clearer, and it may be possible to find a way to get the best of both in a final DD.
Your goal in building the DD is to create the cleanest design with minimal coupling through well defined interfaces. It is hard to judge exactly when you reach that point, but such design is often referred to as 'elegant'. This is more of an artistic judgment than a scientific one and the best designers have that ability. They can also tell when a design is inelegant or clumsy without being able to specify the exact reason why.
The process I have described will not create an elegant design without good judgment on the part of the designers. A good DD will reduce the effort to build the system and its entropy at the start of a system's life. An elegant one will improve on that design. If the DD is used to guide the enhancements, it will minimize the increase of entropy caused by those changes. The benefits of all this work will be faster and easier programming, fewer bugs and a longer system lifetime. All of this translates into reduced costs and improved performance, not a small accomplishment in today's complex environment.