A database application isn't complete until you've prepared professional-grade documentation for each element of the application. The "Visual C++" qualifier is missing from the preceding truism of professional database developers because this statement applies to all database applications created with any front-end development tool or programming language. Visual C++ doesn't provide any documentation tools specific to database applications, and what is provided (help file shells and source comments) is rather basic.
This chapter describes the following three basic documentation elements for all database applications:
Data dictionaries that fully describe the tables of the database(s) used by the application and each field of the tables that the application reads or updates. Data dictionaries also specify primary and foreign key fields and relations between tables, as well as security restrictions that apply to the tables. (Some RDBMSs let you enforce security provisions at the field level.) Referential and domain integrity rules that are enforced at the database and table levels, respectively, or that must be incorporated into every application that updates the tables, are also included in the data dictionary.
Code and form printouts that include sufficient commentary to make the source code comprehensible to others who need to maintain the application by revising the code and/or the form design. A programmer should be able to totally reconstruct the original application from this documentation element. Code and form printouts also contain version control information that identifies modifications made to the original code, who made the revisions, the purpose of the revision, and when the revision was made (including the version number to which the revision applies). A flow diagram of the application also aids others who need to understand the concept and construction of your database front end.
User manuals that provide instructions for installing and using the application the way you intended. Regardless of how intuitive your application is or how complete its built-in help system is, a printed user manual should be provided as a distributable item of any database application. Although users seldom refer to printed manuals (except as a last resort), your online help system can be created from the user manual if you have WexTech Systems' Doc-To-Help application, which is described near the end of this chapter. Using Doc-To-Help to create Windows help files is covered in Chapter 23, "Creating Help Files for Database Applications."
The major sections of this chapter deal sequentially with each of the documentation elements in the preceding list.
Preparing a Data Dictionary
Data dictionaries are the most important element of database documentation. If you use a product such as Asymetrix's InfoModeler, the process of documenting the database will be a bit easier. InfoModeler provides a vast array of printed reports, tables, and charts to document your database. This chapter describes some of InfoModeler's capabilities, as well as other database documentation techniques.
At the very least, data dictionaries should include the following components:
A narrative description of the purpose and overall structure of the database.
A detailed description of each table in the database, usually in tabular format.
The name of each field of the tables in the database, together with the field data type and field size (if not determined by the field data type).
Entries that identify primary and foreign key fields in each table.
A list of constraints (validation rules) for field values that are used to maintain domain integrity and an indication of whether these constraints are enforced at the table level by the RDBMS or must be maintained by application code.
A graphical or tabular description of the relations between the key fields of the tables and an indication of whether the relational integrity is enforced by the RDBMS or by applications.
A list of stored procedures and triggers, including the source code for the stored procedures and triggers, if the RDBMS supports these features.
The following sections describe writing your own Visual C++ application to create a data dictionary, using a CASE tool to create an Access database (including a data dictionary for the database), obtaining table data from Access's Database Documentor (described later), and using a commercial Access documentation tool such as InfoModeler to create data dictionaries for Access databases. The emphasis of this chapter is on the .MDB database format, because the Access database structure is the most likely to be used in the majority of new Visual C++ applications.
Writing a Visual C++ Application to Create a Data Dictionary
It's relatively easy to write a Visual C++ database application to create a fully formatted data dictionary as a text file that you can import into Word for Windows or any another word processing or spreadsheet application. It's an even simpler process if you've created (or have access to the source code for) a data dictionary generator for Access databases that relies primarily on C or C++ code.
DOCDB, the sample data dictionary application that is described in the following sections, is based on the ODBC access routines described in Chapter 7, "Using the Open Database Connectivity API."
DOCDB is a simple form-view Visual C++ program. It was originally developed with Visual C++ 1.5 and was then recompiled as a 32-bit application using Visual C++ 4. It's not uncommon to have to convert 16-bit applications to 32-bit when you're converting to either Visual C++ 2.x or 4. The 32-bit version of DOCDB is available on the CD that comes with this book.
DOCDB performs a simple task: It provides all the information that ODBC can provide about the columns in a specified table. This information is presented in a form. It would be easy to add report printing capabilities to DOCDB, and even to add the capability to report on all tables in a given database when you create a printed report. However, printed reports would be secondary to adding additional functionality to DOCDB to enhance DOCDB's retrieval of information about a database.
DOCDB is a simple program. It was created using AppWizard, with only two changes to the default "stock" program: It is a Single Document Interface (SDI) program with a CFormView view class. Neither database nor OLE support has been added to DOCDB, because these features weren't needed.
After DOCDB has been created, the first step is to incorporate the ODBC routines. Adding this support is detailed in Chapter 3, "Using Visual C++ Data Access Functions," and it consists of these steps:
Copy the ODBC helper routines (ODBC1.C, ODBCMISC.H, ODBC2.CPP, ODBCTABL.CPP, and ODBCINFO.CPP) to the \DOCDB directory.
Edit the DOCDB project and add the ODBC helper source files (the .CPP and .C files from step 1) to the project.
Edit the ODBC C/C++ source files and add this DOCDB header file #include statement:
#include "odbcmisc.h"
Copy the dialog box templates from ODBC.RC to the DOCDB resources.
Add the ODBC library to the ODCDB library list.
You can refer to Chapter 3 for more-detailed steps if you need to.
After you've followed the preceding steps, you can do a test compile of the ODCDB project. If the compilation succeeds without errors, you can continue to create the DOCDB program.
The next step is to use the resource editor to add the controls to the DOCDB main dialog box. Figure 22.1 shows this dialog box, including the dialog control IDs.
All unmarked controls in Figure 22.1 are IDC_STATIC.
Each control in DOCDB must be bound to a variable, with the exception of the New Database button, which has an attached function, and the Column Name combo box, which calls a function whenever the current selection (the column in the table) has changed. The dialog is managed by the CDocdbView class (found in DOCDBVW.CPP).
After the dialog box has been created, in Visual C++ use ClassWizard to bind variables to the controls, as shown in Table 22.1.
Table 22.1. Variable names for DOCDB's controls.
Control
Variable Name
Variable Type
Description
IDC_COLUMN
m_ColumnList
CComboBox
The list of all the columns in the selected table is stored here. This is both an input and an output control.
IDC_CONNECT
m_Connect
CString
This output control shows the current connect string.
IDC_DATASOURCE
m_DataSource
CString
This output control shows the datasource name.
IDC_DATATYPE
m_DataType
int
This output control shows the column's data type.
IDC_NULLABLE
m_Nullable
int
This output control indicates whether the column supports nulls.
IDC_OWNER
m_Owner
CString
This output control shows the table's owner.
IDC_QUALIFIER
m_Qualifier
CString
This output control shows the table's qualifier.
IDC_RADIX
m_Radix
int
This output control shows the column's radix, if applicable.
IDC_REMARKS
m_Remarks
CString
This output control shows remarks on this column, if any.
IDC_SCALE
m_Scale
int
This output control shows the scale of the column, if applicable.
IDC_TABLENAME
m_TableName
CString
This output control shows the name of the table.
IDC_TYPENAME
m_TypeName
CString
This output control shows the column's data type, in character format.
IDC_PRECISION
m_Precision
int
This output control shows the precision of the column.
IDC_LENGTH
m_Length
int
This output control shows the length of the column.
IDC_TABLE
m_Table
CString
This output control shows the name of the current table.
Although DOCDB can show information about columns in a table in a database, it's important to realize that not all ODBC drivers can return all the information. For example, in a text datasource (such as a CSV file), it isn't reasonable to have remarks, scale, or precision information. In fact, most ODBC drivers don't return all the information that DOCDB tries to display. Any information that is unavailable will be displayed as either a blank or a zero, depending on the variable's data type.
When Visual C++'s ClassWizard binds a variable to a control, it creates the code to initialize the variable and to actually transfer the variable's contents to the control. When there must be conversions (such as the conversion of integer variables to text for edit controls), the DDX_Text() macros take care of this conversion automatically.
In addition to binding variables to the controls (as described earlier), it's necessary to also have functions for the IDC_NEWDB button and the IDC_COLUMN combo box. Using ClassWizard (see Figure 22.2), create two functions. For the IDC_NEWDB button, create a function for the message BN_CLICKED. This function will be called each time the user clicks the New Database button. For the IDC_COLUMN button, create a function for the message CBN_SELCHANGE. This function will be called each time the user changes the current column in the table.
The only changes you need to make to the code created by AppWizard are in DOCDBVW.CPP. You must add the functionality of the two functions created by ClassWizard. Listing 22.1 shows DOCDBVW.CPP. All the code that must be added appears in bold.
In this listing you see how the ODBC helper routine GetODBC() has been called, which prompts the user for database, table, and (if applicable) directory names. The names will be stored in the locations specified in the call:
After you have the name of the database and table, you can open the database and determine attributes. This is done using the SQL...() functions, which are described more fully in Chapter 3.
The process of using a database consists of the following steps:
Allocate the environment using SQLAllocEnv(). This function takes only one parameter, a pointer to an unused environment handle.
Allocate the connection using SQLAllocConnect(). This function takes two parameters: the environment handle (returned by the SQLAllocEnv() function) and a pointer to a database connection handle. The connection handle is then used by virtually all the other SQL...() functions.
Connect to the database using SQLConnect() (or SQLDriverConnect()) and the connection handle that was returned by the SQLAllocConnect() function, as well as the database connection information such as the database name, user name, and password.
After connecting to the database, you must allocate a statement. You do this with the SQLAllocStmt() function.
After the statement has been allocated, you can issue an SQL command. For example, you could issue a SELECT * FROM statement to get records from each column in the database. The actual fetching of the data from the columns would be done in a loop that has an SQLFetch() call.
When the application is done with the database, you must free the statement handle, disconnect from the database, free the connect handle, and free the environment handle. You do these steps in the opposite order of steps 1 through 4.
The following code fragment shows the function that gets information about the columns in a given table. All the lines that aren't directly related to the database process have been eliminated:
Adding CTL3DV2V2.DLL to Create Three-Dimensional, Shaded Dialog Boxes
No accoutrements, such as progress-metering gauges, are added to DOCDB, because one of the purposes of this sample application is to demonstrate the ease with which databases created with Access can be accessed by Visual C++ applications. However, the CTL3DV2.DLL library is used to add a gray background and a 3-D effect to dialog boxes and message boxes under some versions of Windows.
NOTE
At this stage in the life of Windows, only Windows 3.x and Windows NT really need to use CTL32V2.DLL. Windows 95 has this functionality built in. However, there is a version of CTL32V2.DLL for Windows 95 for applications that need it.
CTL3DV2.DLL is a small (about 25K) library that is included with Visual C++, Microsoft Office, and several other Microsoft applications. CTL3DV2 can be found in the \REDIST directory, where the ODBC and SQL redistributable components reside.
Because CTL3DV2.DLL is included as part of ODBC's installation, you can generally assume that most users of Windows database applications have a copy of CTL3DV2.DLL in their \WINDOWS\SYSTEMS directory. Excel 5, Word 6, and other Microsoft products released in late 1993 use CTL3DV2.DLL rather than CTL3D.DLL because of problems caused by incompatible versions of CTL3D. Some software suppliers modified CTL3D for their applications without renaming the files. There are also several versions of CTL3DV2.DLL, some of which might not be compatible with Visual C++ and the current releases of other Microsoft applications. The version used in DOCDB is dated 9/16/95, has a file size of 27,136 bytes, and is for Windows NT. For Windows 95, this file is 26,624 bytes long and is dated 9/16/95. CTL3DV2.DLL files with dates later than mid-1995 (when Windows 95 was released) that have approximately the same file size should work as well, because Microsoft often redates files using the release date of the product that the file is distributed with.
TIP
You can obtain a copy of CTL3DV2.DLL by copying it from the \MSDEV\REDIST directory from your Visual C++ CD. For applications that will be created to run solely under Windows 95, you don't need to include CTL3DV2, because this functionality is built into Windows 95. Windows NT users should use the file CTL3D32.DLL (or copy it and rename it CTL32NT.DLL), which is in the \MSDEV\REDIST directory on the Visual C++ 4 CD.
NOTE
The CTL3DV2.DLL and CTL3D32.DLL libraries are copyrighted by Microsoft, and the license to distribute Microsoft's copyrighted files in conjunction with your Visual C++ applications does include the right to distribute CTL3DV2.DLL as part of the OLE and ODBC distribution kit you include with your applications. You need to determine whether prospective users of your applications currently have access to CTL3DV2.DLL from \WINDOWS\SYSTEM on their local computers. If it isn't installed, you must install it. If it's already installed, and it's an older version than the one your application is supplying, you should replace it.
Running DOCDB
To run DOCDB, follow these steps:
Create and compile the DOCDB project. The source is on the source code disk. Alternatively, you can create your own project using the listings from this chapter. If you're not comfortable using Visual C++, practice by creating your own version of DOCDB.
Start the DOCDB program, shown in Figure 22.3. You can run DOCDB either from the Visual C++ workbench or from Windows.
Select the from the list the database you want to open. If your database hasn't been installed in the ODBC system, install it and rerun DOCDB. Click the New Database button to display the SQL Data Sources dialog, shown in Figure 22.4. Figure 22.5 shows the NorthWind example opened in DOCDB.
If you receive an Error Opening File message, or if the Column Name combo box is blank, open the database in Access and make sure that the Admin user (or your user ID) has read permissions on all system tables in the database.
TIP
You can compare the speed of operation of Access and Visual C++ database applications on your computer by timing the execution of both a Visual C++ application and an equivalent application that runs under Access.
Also, if you're competent with Visual C++ 4's DAO, you might want to compare DAO with both ODBC and Access. The results might be enlightening!
Altering the Visual C++ Code in DOCDB
You have the capability to print reports that contain the information that DOCDB displays in its main window. A CFormView application doesn't have printing enabled by default, and there is no code to print the window's contents. However, it's not difficult to take the information contained in the Columns[] array and format a simple report for your records. The SQLGetInfo() function will return a vast amount of information about drivers, SQL, and datasources.
Exporting Access's Database Documentor Output
Access 2's Database Documentor lets you export a database document report; however, it won't export the subreports. This makes the exporting of database documents virtually useless. There is a solution, however, that requires only a minimal amount of work. You must install a generic, text-only printer in Windows, and then assign this printer to a file instead of a printer port. When the Database Documentor report is printed, it will be printed to a standard ASCII file. You can then import this file into Excel as desired. This problem has been fixed in Access 7, which exports in text formats and as an Excel spreadsheet.
NOTE
Access 7 allows you to directly save your documentation in an Excel, RTF, or DOS text format. If you will be using this documentation in Excel, you should export it directly in the Excel format rather than trying to load the text-formatted file into Excel.
Listing 22.2 shows the NorthWind database documentation saved using the technique just described. This file can be saved directly in an Excel or Word (RTF) format or in a DOS text file format. Of course, any formatting that the report originally contained will be lost if exported in a DOX text file, but the report's information will be complete. In Listing 22.2, I've included only one table for the sake of brevity. The full report as produced by Access is over 50 pages long. (You can find this listing on the CD that comes with this book. It's called rptObjects.txt.)
Listing 22.2. NorthWind documented by Access's Database Documentor.
Thursday, January 18, 1996
Table: Categories Page: 1
Properties
Date Created: 3/17/94 3:01:37 PM Def. Updatable: True
Last Updated: 3/17/94 3:02:46 PM Record Count: 8
Columns
Name Type Size
Category ID Number (Long) 4
Allow Zero Length: False
Attributes: Fixed Size, Auto-Increment
Collating Order: General
Column Hidden: False
Column Order: Default
Column Width: 1110
Description: Number automatically assigned
to new category.
Ordinal Position: 0
Required: False
Source Field: Category ID
Source Table: Categories
Category Name Text 15
Allow Zero Length: False
Attributes: Variable Length
Collating Order: General
Column Hidden: False
Column Order: Default
Column Width: 1395
Description: Name of food category.
Ordinal Position: 1
Required: True
Source Field: Category Name
Source Table: Categories
Description Memo -
Allow Zero Length: False
Attributes: Variable Length
Collating Order: General
Column Hidden: False
Column Order: Default
Column Width: 4380
Ordinal Position: 2
Required: False
Source Field: Description
Source Table: Categories
Picture OLE Object -
Allow Zero Length: False
Attributes: Variable Length
Collating Order: General
Column Hidden: False
Column Order: Default
Thursday, January 18, 1996
Table: Categories Page: 2
Column Width: 1470
Description: A picture representing
the food category.
Ordinal Position: 3
Required: False
Source Field: Picture
Source Table: Categories
Relationships
Reference1_Products
Categories Products
Category ID 1 Category ID
Attributes: Enforced
Attributes: One-To-Many
Table Indexes
Name Number of Fields
Category Name 1
Clustered: False
Distinct Count: 8
Foreign: False
Ignore Nulls: False
Name: Category Name
Primary: False
Required: False
Unique: True
Fields: Category Name, Ascending
PrimaryKey 1
Clustered: False
Distinct Count: 8
Foreign: False
Ignore Nulls: False
Name: PrimaryKey
Primary: True
Required: True
Unique: True
Fields: Category ID, Ascending
Thursday, January 18, 1996
Database: I:\Database Developers Guide with Visual C++ 4\Source Page: 3
CD\NorthWind 7.mdb
Properties
AccessVersion: 06.68 Build: 4
Collating Order: General Def. Updatable: True
Query Timeout: 60 Records Affected: 0
Transactions: True Version: 3.0
User Permissions
admin
User
User1
Group Permissions
Admins
Users
Thursday, January 18, 1996
Relationships: All Page: 4
Relationships
Reference
Customers Orders
Customer ID 1 Customer ID
Attributes: Enforced, Cascade Updates
Permissions: One-To-Many
Reference1
Suppliers Products
Supplier ID 1 Supplier ID
Attributes: Enforced
Attributes: One-To-Many
Reference1_Products
Categories Products
Category ID 1 Category ID
Attributes: Enforced
Attributes: One-To-Many
Reference2
Products Order Details
Product ID 1 Product ID
Attributes: Enforced
Attributes: One-To-Many
Thursday, January 18, 1996
Relationships: All Page: 5
Reference3
Shippers Orders
1
Shipper ID Ship Via
Attributes: Enforced
Attributes: One-To-Many
Reference4
Orders Order Details
1
Order ID Order ID
Attributes: Enforced, Cascade Deletes
Attributes: One-To-Many
Reference5
Employees Orders
Employee ID 1 Employee ID
Attributes: Enforced
Attributes: One-To-Many
Of course, you can simply print the report generated by the Database Documentor using a high-quality printer. Figure 22.6 shows the first page of the report in Access. The actual printout is identical to the screen image.
Using Access's Database Documentor to Document Databases
Access 2's Database Documentor lets you create tables you can use to develop a data-dictionary application. The Database Documentor is located under Tools | Analyze | Documentor in Access 7.
To use the Database Documentor to create information from which you can build a data dictionary, follow these steps:
Launch Access's Database Documentor by selecting Tools | Analyze | Documentor. You will see the Database Documentor dialog, shown in Figure 22.7. If you want to, you can use this dialog to display a list of all the objects in the currently open database by changing the Object Type selection.
Click the Select All button to select all the tables, and then click the OK button to display the results of Database Documentor. You can add the tables to any Access database file, including the database that you're analyzing. In this case, select NorthWind.MDB and click the OK button to start the analysis.
After a period of intense disk activity, you will see the results of Database Documentor. When you have finished viewing the results (and printing, if desired), you can simply close the Database Documentor window.
Documenting Databases Created with CASE Tools
If you create your Access or client-server databases with a computer-aided software engineering (CASE) tool, such as Asymetrix's InfoModeler, you can expand the contents of your data dictionary to include descriptions of the underlying object types, fact types, and constraints from which the design of the database is created. Using InfoModeler to create Access databases is one of the subjects of Chapter 4, "Optimizing the Design of Relational Databases." Figure 22.8 shows part of one page (Advertising) of the database diagram of the MailOrder tutorial application that accompanies InfoModeler version 1.5.
All the information about object types, fact types, and constraints is stored in a repository, a database that contains information about databases. Using InfoModeler's reporting features, you can create a report that you can integrate with a data dictionary for the database that InfoModeler creates for you. A part of the report that InfoModeler creates for the Advertising element of the MailOrder application is shown in Figure 22.9. (The entire report is eight pages long.)
After you've completed your database design, InfoModeler creates the database for you. If you have the retail version of Access, you can create an Access database. Otherwise, InfoModeler creates the ANSI (generic) SQL statements required to build the database. Figure 22.10 shows Access's design-mode view of the CoopAd table. InfoModeler creates the CoopAd table from the information stored in the repository that underlies the database diagram shown in Figure 22.8 and that is described in the report file, part of which appears in Figure 22.9.
One of the advantages of using a CASE tool such as InfoModeler is that you can include the table and field descriptions in your data dictionary. The table and field descriptions originate in InfoModeler, not in Access, so the values of the Description property of the Table and Field objects that InfoModeler creates are available to your data dictionary application. You'll need to dig a bit, however, to obtain the data from Raima's Vista database, which is used as InfoModeler's repository.
Using Total Access to Create a Data Dictionary
Financial Modeling Specialists (FMS), Inc.'s Total Access is an Access 2 library database that you attach to the retail version of Access using a setup program supplied by FMS. FMS's Total Access provides comprehensive documentation and analysis of Access databases, not just the simple listing of some table and field properties that Access's Database Documentor generates. Total Access includes a large number of built-in reports that you can use to print a complete description of the database, including a detailed data dictionary for Table and Field objects. You also can modify Total Access's reports to suit your own requirements.
Total Access generates thorough documentation for all Access database objects. Figure 22.11 shows Total Access's Document Form, which corresponds to the Database Analyzer, with NorthWind.MDB as the active database. If you're using Access databases only with Visual C++ applications, you'll only be able to take advantage of Total Access's Table and Queries documentation features.
Start Total Access by selecting File | Add-ins | Total Access Analyzer. After you've selected the objects you want to document, click the Next button and wait while Total Access does its job. A progress monitor shows you how much of the documentation process has been completed. Preparing the documentation for the 125 objects of NorthWind.MDB (everything in the NorthWind.MDB database) took about 10 minutes on a Pentium server and a Pentium 90 computer with 32M of RAM and a total of 6 gigabytes of high-speed SCSI fixed-disk space. If you limit your documentation to tables and queries, for example, this processing time will be less.
Figure 22.11 shows all objects contained in NorthWind.MDB following an analysis.
After Total Access builds the required tables, creating and printing reports such as the Table Dictionary shown in Figure 22.12 is a fast process.
One of the principal benefits of using Total Access for creating data dictionaries is that you can open TA2DOC_C.MDA as a database in your Visual C++ data dictionary generator. Total Access creates one or more internal tables with a TA2_ prefix for each class of Access database object. Figure 22.13 shows part of the TA2_OutputFields table for the NorthWind.MDB database. Total Access includes the Description properties of Table and Field objects in its tables and reports. FMS obtains this information by opening each Table object in design mode and reading the value of the property.
Despite the almost universal reluctance of software users to refer to printed manuals, your application isn't complete until you've written its user documentation. Relying on users to read or print the README.TXT file that accompanies your application before installing it is seldom an effective approach. Most users will simply insert your distribution disk 1 in a drive, choose File | Run from Program Manager, type a:\setup or b:\setup in the Command Line text box, and then click the OK button. If this entry doesn't work, the user next tries a:\install or b:\install. When this fails, he might read the "Installation" section of your documentation. It's more likely, however, that the user will call you to find out what's wrong. Microsoft reports that the vast majority of the questions posed to members of the Product Support Staff for Access can be answered in either README.TXT or the documentation that accompanies Access. The same is undoubtedly true for Visual C++.
Of course, you could be smart and include installation instructions on the label of the first disk of your application. If the installation instructions don't fit on the label, the installation is probably too complex and should be reworked.
Remember that Windows 95 has specific installation requirements, many of which are discussed in Chapter 24, "Creating Distribution Disks for Visual C++ Applications." You should also refer to the Windows 95 documentation for more information about the Windows 95 logo requirements.
The Structure of User Manuals
The structure of user manuals for Visual C++ is similar to that of a book, even if the manual contains only a few pages. The following three sections describe the basic structure of a conventional software user manual.
NOTE
Much of the material in the following sections is based on information contained in Graphic Design for the Electronic Age by Jan V. White, a Xerox Press book published by Watson-Guptill Publications of New York. The book's subtitle, The Manual for Traditional and Desktop Publishing, aptly describes its content. Graphic Design for the Electronic Age provides background and pointers on type selection, page design, and publication construction.
Front Matter
Front matter for user manuals usually is more extensive than that for a conventional textbook and follows the general structure of the front matter for computer software tutorial and reference works, such as this book. The following are the elements of front matter for a typical user manual:
Title page, which includes the name of the application, the version number(s) of the application to which the manual applies, the publication date, the copyright information, the name of the author and the sponsoring organization (if applicable), and similar information.
Introduction and acknowledgments, both of which are optional in application manuals. The introduction might include a brief description of the application and its objectives, as well as the objective of the manual.
Typographic conventions, which describe how the text is formatted to distinguish information you read on-screen or type on the keyboard from the rest of the text. Conventions used to describe multikey operations, such as Alt-key or Ctrl-key, also are included in the front matter. The typographic conventions section should precede the first use of the conventions in the manual.
Equipment requirements, which list the minimum PC configuration required to run the application. This section should include descriptions of any special hardware (such as a mouse), network connections, or software that is required to make full use of the application. In addition to minimum RAM requirements, you should specify the amount of free disk space required to install the application, separated into space required in the application's home directory and in the \WINDOWS and \WINDOWS\SYSTEM directories.
Installation instructions, which describe the procedure required to set up the application. If the application makes changes to the user's CONFIG.SYS, AUTOEXEC.BAT, WIN.INI, or SYSTEM.INI files, these changes should be described in this section. A list of files that the installation requires and the location of those files also should be included here or in an appendix.
Uninstall instructions, which describe the process of removing the application from the user's disk drive. This includes undoing changes made to WIN.INI, SYSTEM.INI, and any other private initialization files, such as MSMAIL.INI. Alternatively, uninstall instructions can be located in an appendix.
Other front matter that won't be incorporated into the online help file. An example is a bibliography, which lists other publications needed to use the application effectively or that describe how the application is integrated into a suite or collection of applications.
Table of contents, which diagrams the book's structure. The table of contents (TOC) should include the titles and page numbers of each of the chapters or the principal elements of the book. The Contents choice of the help file is based on your manual's TOC.
Except for the table of contents, front matter normally isn't included in the online help file for your application. You can move the installation instructions to the text section of the book if you want, but the preferred location is close to the front of the manual. Users are more likely to refer to the instructions if they appear in the first few pages of the manual.
Text
The text of manuals usually is broken into chapters and sections. If the manual consists of more than about 10 chapters, you might want to break the text into collections of related chapters, called parts. If your manual contains a tutorial and a reference guide for the application, separate parts should be assigned to contain the chapters in each category. The text component of the manual is used to create the online help file. Separate help files often are used for the tutorial and reference parts.
Back Matter
Material that is supplemental to the text or that assists readers in understanding the text is included in the back matter. Back matter may contain the following elements:
A glossary, which explains terms that might be unfamiliar to readers. A good practice is to explain unfamiliar terms when they're first used and to include the explanation in the glossary. This lets the reader look up the meaning of the term if he or she missed the initial definition.
An appendix, which might include "Most-Frequently-Asked Questions," a list of error messages (and explanations of why the errors occur and what to do when the user encounters them), a general troubleshooting guide, and, if necessary, an abbreviated data dictionary for the database(s) used by the application.
An index, with references to the page number(s) for all significant topics covered in the text. The index serves as the list of search terms for your online help file. Reviewers of software documentation consistently pan user manuals that don't include complete and accurate indexes.
Adding the glossary to the online help system is optional but recommended. Appendixes don't usually appear in help files, and the index serves as the backbone of the search topics in the help system.
Using Doc-To-Help to Create Convertible Manuals
WexTech Systems, Inc.'s Doc-To-Help application consists of a set of templates for Word for Windows that are specifically designed for writing software user manuals, plus other files that are associated with converting the manuals into Windows WinHelp (.HLP) files. Chapter 23 describes how to use Doc-To-Help to convert the user manuals you write into .HLP files. Standard templates are included for conventional 8 1/2- by 11-inch manuals with conventional section headings, like those used in this book (D2H_NORM.DOT), or a side-head style, in which the headings appear in the left margin (D2H_SIDE.DOT). Doc-To-Help also supports the standard 7- by 9-inch manual format (D2H_SMAL.DOT). Figure 22.14 shows a WexTech sample file, D2HINTRO.DOC, that uses D2H_NORM.DOT opened in Word for Windows.
Doc-to-Help comes in two versions. Version 1.7 supports both Word 2 and Word 6. Version 2 supports Word 7. There is an upgrade path to let Doc-To-Help 1.6 users upgrade to either version 1.7 or 2 as needed.
Although you can write manuals that you can convert to WinHelp .HLP files with any word processing application that supports footnotes and can export text and images as Microsoft rich text format (.RTF) files, using Word for Windows together with Doc-To-Help saves considerable time in creating the printed version of your manual. Doc-To-Help's standard templates provide the foundation for attractively formatted manuals, but you can alter the styles employed by the standard templates if you need to conform to company-wide publication standards. Figure 22.15 illustrates Doc-To-Help's standard 8 1/2- by 11-inch manual style. The major time-saving feature of Doc-To-Help—and thus the principal justification for acquiring Doc-To-Help—is the ease with which you can compile your manuals into WinHelp .HLP files that provide access to almost every feature offered by the Windows 3.1 version of WINHELP.EXE.
This chapter described several methods of creating data dictionaries for your Visual C++ database applications, how to use a commercial cross-referencing application to document your Visual C++ code, and the basic structure of the printed manual that should accompany every production database application.
The next chapter shows you how to use WexTech's Doc-To-Help to convert user manuals to Windows WinHelp files.
SOFTWARE FOR SALE
SEARCH CENTRAL
REFERENCE
JOURNAL
COMMUNITY
ABOUT US
