Understanding the Specifications Puzzle

By: Tim Bryce

"You like potato and I like potahto
You like tomato and I like tomahto
Potato, potahto, Tomato, tomahto."
Let's call the whole thing off."

- Lyrics by Ira Gershwin; Music by George Gershwin

Defining specifications for the design and development of systems and software is a lot like this classic Gershwin song and what I personally regard as the biggest cause of confusion in the Information Technology field for as long as I can remember, which is over 30 years in the industry. Some people say specifications should be based on the inherent properties of information, others believe it is based on a screen/report or file layout, yet others adamantly believe it should be based on process and data specifications. Interestingly, all are absolutely correct. The difference lies in the perspective of the person and the work to be performed. For example, how we define specifications for the design of an automobile is certainly different than how we specify a skyscraper. The same is true in the I.T. field where we have different things to be produced by different people; for example:

1. THE PROGRAMMER (aka, Software Engineer) requires precise specifications in order to develop program code (source and object). This normally takes the form of processing requirements (e.g., hardware configuration, types of transactions to be processed, volume, timing, messages, etc.) and physical data requirements (input/output/file layouts).

2. DBA (Data Base Administrator) requires precise specifications in order to select a suitable file management technique (e.g., DBMS) and produce the necessary Data Definition Language (DDL) for it. This normally takes the form of a logical data base model representing relationships between data entities.

3. THE ANALYST (aka, Systems Analyst, Systems Engineer, Systems Architect, Business Analyst) - requires specifications about the end-User's information requirements in order to design a system solution. This is normally based on a definition of the user's business actions and/or decisions to be supported. Following the system design, the Analyst produces the specifications required by the Programmer and DBA to fulfill their part of the puzzle. From this perspective, the Analyst is the translator between the end-User and the Programmers and DBAs.

Each party has his own unique perspective of the puzzle and, as such, requires different "specifications." To compound the problem though, the role of the Analyst sharply diminished over the years, leaving it to the Programmers to try and determine what the end-User needs, a skill they are typically not trained or suited for. To illustrate, I am reminded of the story of the IT Director at a shoe manufacturing company who received a call from the corporate Sales Manager asking for some help on a pressing problem. The IT Director sent over one of his programmers to meet with the Sales Manager and discuss the problem. Basically, the manager wanted a printout of all shoe sales sorted by model, volume, type, color, etc. The programmer immediately knew how to access the necessary data and sorted it accordingly thereby producing a voluminous printout (three feet high) which he dutifully delivered to the user.

The IT Director stopped by the Sales Manager's office a few days later to inquire if the programmer had adequately serviced the user. The sales manager afforded the programmer accolades on his performance and proudly pointed at the impressively thick printout sitting on his desk. The IT Director then asked how the manager used the printout. He explained he took it home over the weekend, slowly sifted through the data, and built a report from it showing sales trends.

"Did you explain to the programmer you were going to do this?" asked the IT Director.

"No," replied the Sales Manager.

"Aren't you aware we could have produced your report for you and saved you a lot of time and effort?"


This is a classic example of the blind leading the blind. The user did not know how to adequately describe the business problem, and the programmer asked the wrong questions. Remarkably, both the Sales Manager and programmer were delighted with the results. The IT Director simply shook his head in disbelief.

There are substantial differences between specifying information requirements and specifying software. Both have their place, but both serve different purposes. Whereas a true Analyst investigates the underlying business rationale of the information, the Programmer lives in the physical world and is only concerned with how the software will work.

It is not uncommon to hear programmers lament, "Users do not know what they want." They may not know how it should physically look or how it should best be delivered, but Users most definitely know what they want from an information point of view. Most programmers simply are not asking the right questions. Then again, they were not trained for this and are trying to compensate for the lack of true Analysts.

Remarkably, the Analyst function is experiencing a resurgence in the industry as companies are realizing that a higher level person is needed to understand the business and have a more global perspective of a company's systems and software. To illustrate, the process should fundamentally work like this:

1. Working with the User, the Analyst studies the business and helps the User specify information requirements.

2. From the requirements, the Analyst produces a system design which includes either a new system and/or modification of an existing system. As part of the design, the Analyst defines:

* The logical processing of data in terms of how it is to be collected, stored, and retrieved.
* The business processes affected, including the parts implemented by the computer.
* The design of the inputs and outputs.
* The design of the logical data base model.

In considering the computer processing, the Analyst determines which portions can be implemented by a commercial package or requires programming.

3. The design specifications are conveyed to the Programmer and the DBA for implementation.

4. From the logical data base model, the DBA designs a physical solution and produces the necessary Data Definition Language. The DBA passes on the physical file layouts to the Programmer for implementation.

5. The Programmer studies the software specifications and determines a suitable method of implementation, e.g., languages to be used, along with suitable tools and techniques for design.

For graphic, see:


The real beneficiary of such an approach is the programmer as the "guess work" has been eliminated for him. This may be an oversimplification of the overall process, but it is intended to show the vital role the Analyst plays and how it contrasts with the other participants. In the absence of such a person, the Programmer inevitably defaults to the role of Analyst and here is where specification problems begin to emerge.

This also hints at the limitations of "agile" methods. To their credit, the proponents of such methodologies recognize they are limited to software and, in particular, a single program. In doing so, they are trying to expedite the overall process of specification gathering in order to get to the job of programming.

In addition to defining the relationships between the various development functions, there is also the problem of developing a standard and consistent approach for recording specifications. This can be performed orally, but more likely it is recorded using a documentation technique to communicate the work to be performed and as a means to check the finished product to see if it does indeed satisfy the specifications. In the fields of engineering and construction, standards have been developed over the years to record specifications, such as blueprinting. But in the I.T. field, a myriad of techniques have been introduced with little or no standardization. For example, there are several different types of graphical and textural techniques, as well as repositories and data dictionaries to record and track specifications. Regardless, very few companies have adopted standards for recording specifications.


The problem with specifications in the design and development of systems and software is primarily due to a lack of standardization in the industry. There are a lack of standards in the areas of:

* Different types of deliverables resulting from the development process and how to format them (including specifications).

* Different development functions participating in the process, along with their interrelationships, and duties and responsibilities.

* Different perspectives of development in terms of the inherent properties of systems and software.

* Different methods, tools and techniques for performing design and development.

As long as there remains a lack of standardization in the I.T. industry, there will always remain a different interpretation of what specifications are and how to best document them. In other words, we'll go on saying "You like tomato and I like tomahto." So when do we call the whole thing off?

If you would like to discuss this with me in more depth, please do not hesitate to send me an e-mail.

"Good specifications will always improve programmer productivity far better than any programming tool or technique."
- Bryce's Law


» More on Programming