Computer System Specifications 1: Communication or Confusion?
Issue No. 21
A computer specification is written to give the person who will use the system and the person who will be writing code a clear picture of what the system is supposed to do. The following are the steps needed to create an understandable and usable specification. These steps are based on real-life examples of specifications that allow the client to say, “Yes – that’s what I need,” and give software developers the information to say, “I know what I need to do.”
1. Understand the client’s business process.
When meeting with a new client, the first objective is to understand the unique, specific way the client’s business works – not the way an existing or proposed computer system works, but the way the business works. Although businesses in the same field may have many similarities, one size does not fit all. Each business has unique characteristics and processes that ensure its competitive advantage. Include a description of the client’s business process in the specification. Words are good, and pictures are better.
2. Speak the client’s language.
A good specification is written in a language the client understands. If a client speaks German, it wouldn’t be productive to send her an email written in Greek. In the same way, if Bob, who owns Bob’s Manufacturing, says, “We maintain the lowest possible level of parts in our inventory,” his specification should use the word “parts” not “items.” Although certain words may seem to be synonyms, company-specific terms are not interchangeable. They’re part of the language and culture of the business. When the client speaks, it’s important to listen and then use the client’s specific terms in the specification.
3. Draw pictures.
Many ambiguities are eliminated with pictures. A client wants to see information in a format that makes business sense, and a software developer creates screens that reflect the underlying computer system. Often these are completely different. Drawing the screen and including the picture in the specification means everybody starts on the same page and gets to a satisfactory result sooner.
4. Talk to the client.
The only way to figure out what a client wants is to meet with the client. Not email. Not IM. Not phone calls. All these tools are useful to clarify the information originally discussed in person, but every good specification starts with face-to-face, real-life conversations between the business person responsible for the system and the person who will write the specification. The discussion should include lots of questions from both the client and the specification writer, which leads to the next point:
5. Listen to the client.
This step should be a given. It’s probably the most important step to take, and it’s also the one most often ignored: LISTEN.
If you’re writing the specification, don’t assume that because you’ve worked with similar businesses you already know all the answers; this will trick you into not listening. Never assume you know the business better than the person who works there every day.
6. Invest the time to create a clear specification.
A good specification includes a lot of information, and it takes a significant investment in time to create it. If you’re writing a specification for a computer system that includes less than six screens and functions, and one person knows all the requirements, you can probably complete the discussion about the system’s requirements in a half-day meeting (or less). As a general rule for larger systems, if the business process is clearly defined, and you’re working with a knowledgeable person (or team), an experienced specification writer may be able to cover one or two screens or functions per hour.
7. Don’t assume a specification is complete.
No matter how well you define requirements, how clear the process is, and how lovely the paper screens look, when people actually begin to use the system, they will come up with new ideas. Don’t be surprised when users also find holes in processes that everyone thought were complete and discover problems with assumptions that seemed sound on paper. Changes mean modifications to the specification.
A specification is only “final” when the code is delivered and the client says, “We’re done.”
8. Get a return on your investment with a clear specification.
A coherent specification saves time and money for both the client and the software developer. Following the above steps – understand the process, use the client’s business terms, draw pictures, ask questions, listen to the answers, and plan enough time – provides a good start on creating a document that actually communicates clearly! Each of these steps will be described in detail in subsequent issues of our newsletter.
What does a bad spec look like?
A client says, “I make money by selling coffee to employees. So, every day when an employee boots his computer, display a picture of a big blue cup of coffee. If it’s before 8 a.m., also show them a digital clock with the current time, so they know they have a few minutes to buy a cup of coffee before they start work.” Unfortunately, the specification often ends up being undecipherable as in the following example.
Nonfunctional requirements: Hex triplet 0000FF recommended for user class “coffee drinker” layer, liquid beverage object. Undetermined hex triplet indicated for numeric output subsystem, though something in the range of 808000 may be architecturally sound. Note: Using the hex triplet allows for more than 16.8 million colors. The hex triplet is a six-digit, three-byte hexadecimal number. To obtain the hex triplet value, convert the decimal RGB value, usually 0-255, by dividing number by 16, ignoring remainder, to get the first hexadecimal digit 0-F, where A-F represents 10-15 (however, if original number is 0 or 1, multiply by 255 before conversion); second digit is the remainder times 16; repeat process for each of the three RGB values.
Functional requirements: Add program to initial boot sequence to ensure application is automatically instantiated on load. Numeric digital output to be clearly readable based on standard 20-20 scale and should derive value from date/time default settings on local system; specific pixel size for “box” (square? rectangle? irregular shape?) to be determined, as is location of communications interface to be displayed in foreground of “box.” Size of container for desired end product to be determined, though recommended standards are specifically 8 fl ozs, 12 fl ozs, and 16 fl ozs. Note: don’t represent non-standard size for customer’s product, because if representation should drive demand, the non-standard size may be obtained only with additional unspecified lead time and at a premium cost.
This example was actually created using techno-terms from real specifications! If the goal of a specification is communication, this example specification gets an F.