Visual Basic 5 - Access 97 System Documentation

[Bruce McCowan <bmccowan -at- GR8DANE -dot- COM>]

Our client is historically mainframe with very little past exposure to PC GUI / database management. The client's application that we are developing / documenting is Visual Basic 5 front end, Access 97 and Crystal Reports 6. The client's permanent application support staff are rather unfamiliar with VB5 in particular. The challenge is to produce technical application documentation that is appropriate for in-house support people who are new to VB and the event-driven paradigm. That is, the right mix of detail, generality, Visual Basic awareness, code maintenance, application support and application troubleshooting is important (as always). We hope that other tech writers can offer some comments and suggestions re the draft outline below. Does the methodology outlined below make good sense given the context described in the opening paragraphs? How much relative emphasis should be placed on the various sections -- more on the event-driven paradigm and less on the sub-procedure code explanations for example? We would also appreciate seeing a sample of technical documentation for a VB / Access application aimed at a similar readership. (Our application (very generally) looks after commissions payable to sales staff.)

Thank you very much for your assistance.

 

Draft Outline For Technical System Documentation Manual (VB 5 / Access 97)

Scope and Purpose of Document

General Purpose / Overview of the Application

General Technical Overview

    Event-Driven Programming Model or Paradigm

        Visual Basic code and front end

        Control / Variable Naming Conventions and other Notations

    Database Overview

        Adding, deleting, modifying records in an Access Database through DAO

    Internal Data Representation and Database Interaction

General Structure

    Visual Basic Project Modules; Configuration Files

Principle Data Access Objects

    Databases

    Table-Type Recordsets; Lookup Table-Type Recordsets

Launch Sequence

Overview of each Form

    List of Command Buttons tabulated against the forms

    Overview of each command button and other controls on the form

    Validations re each command button

Sub Procedures and Functions (Form by Form)

    Complete list of all Sub Procedures / Functions

    Description (length of the code discussion to depend on the Sub / Function)

        what is being passed in (some detail re the influence of arguments)

        what is being returned

Definitions of the Record Sets (SubProcedure by SubProcedure)

    Correlation of the record set variables and the database table / fields

    Gathered through QueryDefs or SQL statements

Writes to Database (SubProcedure by SubProcedure)

    Complete list of all writes: table / field

Error Messages / Meanings / Troubleshooting 

 

Bruce McCowan, P.Eng., Great Dane Consultants, bmccowan -at- gr8dane -dot- com