Newsletters

• Sign up for free newsletter

 

Computer System Specifications 4: Creating A Solid Investment

Issue No. 25

Taking the time to create a clear and usable computer system specification is a solid investment in time and money.

6. Invest the time to create a clear specification.

After completing steps one through five of the eights steps to creating a specification, you may be thinking, “Too much information!” And you’re right. A good specification includes a lot of information, and it takes a significant investment in time to create it. As a general rule, if the business process is clearly defined, and you’re working with a knowledgeable person (or team), you can answer all the questions about one or two screens or functions per hour. If the system includes a number of screens with similar data, and the screens all work the same way, you can define more than two screens per hour.

However, if you’re working with a team that is changing and improving the business process while defining the requirements for a new system, you’ll be lucky to complete one screen per day. Whether the business process is well-defined or not, unless the system is extremely small (less than six screens and functions), don’t expect to complete the requirements gathering in one meeting. After gathering information, you will need more time to document requirements and draw sample screens.

When a clean document is ready, it goes to the business team for review and comments. Plan for this to be an iterative process, because few of us are able to accurately capture 100% of what someone else says. Expect multiple versions of a document before there’s consensus on its accuracy. Don’t underestimate the time required – for both the specification writer and the business team.

7. Don’t assume a specification is complete.

A specification is only “final” when the code is delivered and the client says, “We’re done.” However, unless your system is small and a specification can be completed in a week, don’t wait for a “complete” specification before coding.

A more realistic approach is to identify all the modules or groups of screens that will be in the system, and then work on completing the specification one module at a time. Write the specification for the screens and functions for the module, get client approval, and then hand it off to the development team to begin coding while you and the client begin documenting the next module.

We recognize the risk involved in this approach. Changes requested when the third module is delivered may require developers to modify code delivered with modules one and two. A good development team will plan for this type of change and structure code to make it as painless as possible. Even if the specification is supposedly complete before coding begins, as prototypes are delivered, the client will make changes.

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 they also find holes in processes everyone thought were complete and problems with assumptions that seemed sound on paper.

Unfortunately, waiting for a complete specification before starting to write code extends the project timeline without significantly decreasing the probability of changes to previously delivered code. In fact, delivering screens, even those with minimum functionality, early in the process allows clients to use the system and make decisions that can be incorporated into specifications for modules that haven’t been coded yet.

Plan for change and document it so the specification reflects the actual system.

8. Get a return on your investment with a clear specification.

If the spec is never final and it keeps changing, why bother with all the work? A good specification:

• Gives the client documentation about what they’re going to get.
• Minimizes the time a client has to spend answering questions about how the system should look and work throughout the project.
• Provides programmers with a picture and business rules for how the system should look and function.
• Allows someone other than the programmers and specification writers to test the system.
• Can be the basis for user documentation.
• Is the final authority for answers about how the system is supposed to look and work.
• Documents answers to the question, “Why did we do it this way?”

You will find books and articles that give you an outline of the “key” sections to be included in a good specification, and maybe some of them are useful. However, if you follow the rules above - start with the process, use the client’s business terms, draw pictures, ask questions, listen to the answers, and plan enough time - you’ve got a good start on creating a document that will actually communicate clearly!