VBM Build a Library

VBM - Vision Based Methodology™

Activity 8: Specifying the Vision

Build a Library

Assembling the Technical Design into a cohesive "whole" can be a challenge. If the system is of a large enough magnitude, multiple team members may be involved and various components may be under development simultaneously. Keeping this effort guided in a common direction and insuring that the multitude of designers are producing compatible specifications can be a tremendous responsibility. One approach to making this job easier, is the establishment of a "project library". It can be as simple as some cleared out shelf space or as elaborate as a formal work area, but in either case a common, uniform approach to its organization should be taken.

To start the library, a "binder" approach may the easiest and most hassle-free way to build the initial foundation. For workpapers, general notes, feedback documents, and formal deliverables, the following steps may be appropriate:

  1. Determine an overall organization scheme for all of the expected paperwork.
  2. Make binder assignments for each logical grouping.
  3. Create a binder cover and spine for each of the identified notebooks.
  4. Assemble each of the empty binders using its respective cover and spine.
  5. Create dividers and tabs for each binder to identify its anticipated contents.
  6. Put the completed shell binders into the library.

The advantage of this up-front preparation is that everything collected or produced throughout the phase has a place to be captured and referenced with a minimum of effort. It also discourages documents from disappearing into someone's desk drawer never to be seen by anyone again! Also, the library serves as a central reference point for both the veteran, as well as the new team members.

Another potential use for the library is the storage and maintenance of program specification packets. If the project is of any magnitude, many people may be involved in the specification, review, and coding of each program. Having all of the relevant documentation concerning each program in a single, separate packet per program can make this process straightforward and painless. Again, the organizational approach is similar to creating the binders:

  1. First, assign a thin three ring notebook to each program (Cardboard or Plastic).
  2. Next, insert a set of dividers into each notebook (see the recommended format).
  3. Last, place all of the empty notebooks into the library.

During creation of each of the program specifications, the results can be put into the appropriate notebook. Each packet then becomes a working document throughout the design and programming phases. The initial specification writer has a place to put the results, the specification reviewer has a tangible document to examine, and the ultimate programmer has a packet to study and code from. All of this contributes to the creation of an assignable unit of work that can be maintained within the project library.

Another more subtle advantage is that both the project team as well as interested parties outside of the project, can get a feel for the magnitude of the project simply by taking a quick look at the library. Since both results to date, and the results to come, are reflected within the library contents, an appreciation of the level of progress the team both has achieved and expects to achieve can be gleaned from the library contents.

One approach which has been used successfully is to put some type of status indication on the outside of the binders or specification packets. This provides even more definition to the current state of the library contents. Status could be shown through either a series of check marks or dates on the spine. An alternative to this that works well is the application of colored, removeable stickers to display the current deliverable state (In-Progress, Specified, Coded, Completed, etc.). Whatever way the library is organized and maintained, just the existence of an organized approach to collecting and referencing the team deliverables adds a superior dimension of completeness.

Specify the Components

The creation of high quality program specifications is without question the heart and soul of the Technical Design effort. The entire phase is directed toward creating a detailed, working technical "vision" of the system. Achieving "completeness" at this stage means that all of the details have been fully thought through and completely documented. Each specification "packet" should be independently self-contained, and all relevant information required by the programmer (or code generator) should be complete. Reaching this point requires discipline. The resistance to going the distance in specification creation is still very much alive and well, but fortunately the current methodology trends tend to focus on capturing the details in technical design.

What are the characteristics of a high quality specification? Other than at a high level it provides all of the information necessary to create a program module, here are a few more qualities the System Builder should strive for:

Putting It All Together: A Suggested Specification Packet Format


This section should briefly state the purpose of the program, the major inputs/outputs, and the intended users.

I/O Diagram

The diagram provides a quick "snapshot" of the action. Only a studied glance is required to get an understanding of the mission of the program. This diagram should be a distilled representation of the inputs and outputs, preferably carved directly from the system architecture drawings. This gives the programmer a sense of the scope of the processing, as well as tying the effort back to the global "vision" of the completed system.

Screen/Form/Report Layouts

These represent the visual, communicative business requirements. Each layout should be taken directly from the Business Design Deliverable.

Processing Specifications

Two types of specifications should be placed within this section. First, a diagram which illustrates the functional/structural breakdown of the program. Second, pseudo code or an action diagram for each function/ structure. For example, a COBOL program would be represented by one function/structure per paragraph. Also, these should tie back to the required consistency standard. Typically this is the largest and most detailed specification section.

Data Inputs/Outputs

Place a copy of every file and/or database layout utilized by the program within this section. This will serve two purposes, first it will cause the specification writer to review the current data approach, and second, it will encourage data change requests.

Database Access Calls

Each database access statement should be pre-written and put into the specification packet. These access statements provide the web of connections from the programs to the finalized database design. The process of identifying all the required access paths provides a validation of the current data design and affords the opportunity to make database changes before the programming effort has even started.


If the specification is for an on-line program (window), put a list of all of the screen messages that could be produced during an interactive session into the packet. These usually center around validation errors or functional activity results.

If the specification is for a non-on-line program, put a list of all potential Abend or Error messages into the packet.

Program Test Plan

A unit test plan should be prepared that includes all possible program scenarios (usually on a predefined set of forms). This "checklist" then can be utilized during programming record the completion of each successful test. If the plan is not specified at this time, at a minimum the section and the forms should be included to keep the central repository of information about the program intact and complete.

Walk-Thru History

A short log of each review session and the follow-up results should be maintained (usually on a predefined form). This will aid in maintaining an appropriate level of review rigor throughout the System Design phase.

itmWEB Group LLC, Copyright © 2013, All Rights Reserved