Visual Basic 5 - Access 97 System Documentation

Subject: Visual Basic 5 - Access 97 System Documentation
From: Bruce McCowan <bmccowan -at- GR8DANE -dot- COM>
Date: Fri, 11 Sep 1998 17:17:08 -0400

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
    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

Previous by Author: Re: An Idea: An International Directory of Technical Terms
Next by Author: System Documentation
Previous by Thread: Tools for Writers
Next by Thread: Don't Get Mad at me for this

What this post helpful? Share it with friends and colleagues:

Sponsored Ads