VBM System Documentation

VBM - Vision Based Methodology™

Activity 10: Reselling the Idea

Documentation: Tell'um How to Use It

In order to fully protect the business investment made in a new or modified system, it must be documented. The creation of just a few types of selected references can provide invaluable tools for either the business clients who will utilizing the finished product, or the maintenance programmers who may be making future enhancements. These various references are described below:

System Documentation

If a CASE tool was utilized throughout the effort, the dictionary or encyclopedia should be cleaned-up, organized, backed-up, and filed for future reference. In some cases, printing selected models and data elements in order to provide a paper-based reference source for future quick reference situations can also be helpful.

Depending on the organization, additional formal system binders may need to be created which contain job flows, error response information, special instructions, and timing considerations. Many companies also require system documentation to be entered into either a commercial or a company developed computer-based repository.

User Documentation

Creating high-quality user documentation once again provides another reflection of the quality and professionalism which went into the creation of the new system. In many cases, the user reference manuals directly set the business client's ease-of-use expectations, no matter how well designed the system may be.

Additionally, the client's level of overall system acceptance is closely tied to their perception of the system, simply based on the documentation. If the user guide is disorganized and difficult to use, this can translate directly into a inaccurate perception within the client's mind of a sloppy, difficult to use system. But if the perceived value of the user documentation is positive, especially as it is being used during the transition and learning periods, this can greatly influence the long-term system acceptance, utilization, and success.

Choosing the Approach

It is important to determine the format or combination of formats which will be used to create the business client User Documentation:

Business Procedures

This is still by far the most common approach to creating business client documentation. The standard business procedures manual, which is based on the day-to-day functional procedures a business client must follow in order to accomplish a given task, continues to be one of the most effective reference and training sources available. Usually, these procedures are built around defined business activities, and the associated system steps and processes which will be performed in order to see each of these business activities through to completion. This is the classic "cookbook" approach to documenting a system, and the material is usually organized and reference by business processes.

Technical Reference Manual

This form of documentation tends to be more technical in nature, and it is usually organized around the individual components of the system, rather than the supported business processes. The focus of this reference material is more on the functions, features, and actions required to utilize each of the screens, windows, or batch jobs provided within the system. In addition, further detailed overviews of the individual reports, and an explanation of the information included on each, is also provided. This material is usually organized and referenced by screen hierarchies, screen names, report names, and job names.

On-line Help

On an ever increasing basis, more and more systems are being documented through the use of a text based, on-line help facility. These can literally take the form of electronic reference manuals. Generally, the information contained on-line text files is the same as that which a paper based technical reference might contain. A major advantage of this approach, and one which should encourage the creation of functional documentation in this electronic form, is the instant accessibility, and the direct applicability of the reference information. For the business clients, on-line help is just simpler to use and more readily available.

With the advent of hypertext capabilities, on-line help has even more appeal. Using this approach, the business client chooses highlighted key words contained within the help text itself in order to "skip around" or "drill down" for more detailed or additional information. These highlighted fields are literally text based cross-references which are available at the touch of a button!

Quick Reference Guides

A quick reference guide is a condensed version of either the business procedures, the technical reference manual, or both. Once a business client is familiar with the system, rather than having to utilize a bulky reference manual to look-up a somewhat familiar task, the quick reference guide can provide a shortened version of the steps or actions required to accomplish a desired task. This reference source tends to be focused only on the "how" of a task, leaving the "what and why" to the larger reference manuals.

Quick Reference Cards

For the very common, highly utilized business system steps or screen actions, quick reference cards may be an appropriate and much appreciated source of assistance. These provide instant "memory joggers" for routine activities, and they serve to increase business client confidence when using these highlighted components of the system.

Keyboard Overlays

If special keyboard commands, letters, or keystrokes are required to utilize a unique application, a pre-cut card which fits over the selected keyboard style can provide an instant reference for these special keys. This can aid in learning the commands without frequently referring to reference manuals or on-line help.


In conjunction with classroom type training activities, supplemental training materials can be developed which give the business clients the ability to study independently on an "as needed" basis. These materials can serve to educate a new member of a department, or they can provide a quick refresher for the more experienced folks.

Written Training Manuals

These tend to take the most time to produce, and they can also can become out of date. However, if the system will be stable and a high number of business clients will need to be trained, producing these materials may be worth it. This is especially true if a constant turnover rate exists in the department, or if the system will be used by a large number of people in a significant number of geographic locations.

Training Videos

These can be quickly produced at various levels of professional quality and cost. They tend to be very effective as a quick overview or introduction to the new system. In addition, videos can be produced which cover each of the sub-systems or sub-functions at greater levels of detail.

PC Based Interactive Training

These can be very expensive to create, but they can also be highly effective for individual training. With the multi-media capabilities of today's personal computers, very comprehensive and enjoyable learning "environments" can be created to assist the individual business client. Again, before making this kind of investment, thought should be given to the stability of the system.


One last approach for documenting the system is to create either large fold-out or wall charts which depict the order or flow from one system component to another. This is especially helpful if the system is exceptionally complex, with many procedures or programs which must be performed or executed in a sequential fashion. The charts also help to provide a graphical vision of the system the business clients can see and internalize.

Design, Outline, and Refine

Before developing the documentation, standards should be developed which include the following considerations:

itmWEB Group LLC, Copyright © 2013, All Rights Reserved