One of the most important aspects to writing a comprehensible computer system specification is to make sure the client and the developer are on the same page. To do so, follow the three steps below.
1. Understand the client’s business process.
When walking into a new client’s office, 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 – 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.
As the client walks through his business processes, he steps back and thinks objectively about how the business works. Sometimes this can have an instant benefit of finding things that can be improved immediately. A good software system supports the business’s specific, unique processes; a system that limits a company to doing things just like all its competitors can be a significant liability and may cause a business to lose its competitive edge or even fail.
The overview of the business process should be the first section of any system specification. The benefits of including a text – or even better, a graphical – overview of the business are:
- Gives clients a clear, specific overview of a company’s process that indicates what makes the company great!
- Gives programmers an understanding of the client’s business process that creates a high-level framework for the software to be written and helps establish the importance of the software to the business process.
For example, a client says, “I make money by selling coffee to employees. So, every day when an employee boots her computer, display a picture of a big blue cup of coffee. If it’s before 8 a.m., also show her a digital clock with the current time so she knows she has a few minutes to buy a cup of coffee before she starts work.” In this example, the business process would look something like the following:
2. Speak the client’s language.
A good specification is written in a language the client understands. If your 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. Using a business’s specific terminology means communicating in a way the client understands. Writers also need to remember the business owner does not speak “computer” language. Terms such as “object” and “class” have one meaning in the computer world but have a completely different and more common meaning in the business world outside computers. Avoid using these ambiguous words in their computer context. And completely avoid words such as “hex triplet” that would never be heard outside a software developers’ party.
3. Draw pictures.
Many ambiguities are eliminated with pictures. In the coffee example, the business owner and the person writing the specification could sketch something on a white board or a piece of paper to be sure they each understand how the screen should look. Without a picture, the business owner could be thinking the blue cup looks like this:
While the person writing the specification could be planning for the cup to look like this:
The same misunderstanding could occur with computer system screen design. Including a picture of each screen in the specification eliminates questions. For example, if the screen shown below is included in a specification, the business owner, specification writer, and programmers would know what to expect.
Once you are on the same page as the client about their business process, you need to communicate with the client by talking and listening. Both of these steps will be described in detail in the next issue of our newsletter.
Eight Steps to Creating an Understandable and Usable Specification
- Understand the client’s business process.
- Speak the client’s language.
- Draw pictures.
- Talk to the client.
- Listen to the client.
- Invest the time to create a clear specification.
- Don’t assume a specification is complete.
- Get a return on your investment with a clear specification.