Previous Page TOC Index Next Page Home


32

Documenting Your System

Why Document?

Back in the days of mainframes and very formal centralized MIS (Management Information System) departments, documentation was a mandatory requirement for the completion of an application. Today, it seems as if all types of people are developing applications: administrative assistants, CEOs, sales managers, MIS professionals, and so on. To make matters worse, many of us who consider ourselves MIS professionals never received any formal systems training. Finally, the demand to get an application up and running and then move on to the next application is more prevalent than ever. As a result of all of these factors, it seems that documentation has gone by the wayside.

Despite all of the reasons why documentation doesn't seem to happen, it is as important to properly document your application today as it was in the mainframe days. Documentation provides you and your users with the following benefits:

Preparing Your Application to Be Self-Documenting

Fortunately, Access ships with an excellent tool to assist you with the process of documenting your database. This tool is called the Database Documentor. Although this tool can be used without any special preparation on your part, a little bit of work as you build the components of your application can go a long way toward enhancing the value of the output supplied by the Database Documentor.

Documenting Your Tables

The Database Documentor prints all field and table descriptions entered in the design of a table. Figure 32.1 shows a table in Design view. Notice the descriptions for the ClientID and StateProvince fields. These descriptions provide additional information that is not readily obvious by looking at the field names. The Table Properties window also contains a Description property. This property will be included in the documentation for the table when it is printed in the Database Documentor.


Figure 32.1. Documenting a table by including descriptions of each field.

In addition to enhancing the output from the Database Documentor, entering a table description also assists you and the users of your database when working with the tables in the database. Figure 32.2 shows the Database window after descriptions have been entered for the tables in the database. Notice that the description of each table appears in the Database window.


Figure 32.2. The Database window with table descriptions.

Documenting Your Queries

Just as you can enhance the output that the Database Documentor provides for tables, you can also enhance the output that the Database Documentor provides for queries. Figure 32.3 illustrates the Query Properties window. As you can see, the Description property has been filled in with a detailed description of the purpose of the query. Figure 32.3 shows the description of a query, and Figure 32.4 shows the description of an individual column within a query. Both the query and field descriptions are included in the output provided by the Database Documentor.


Figure 32.3. Documenting a query using the description property.


Figure 32.4. Documenting a column within a query.

Documenting Your Forms

Documentation is not limited to table and query objects. A form has a Description property. It cannot be accessed from the Design view of the form. To view or modify the Description property of a form, follow these steps:

  1. Make the Database window the active window.

  2. Click with the right mouse button on the form for which you want to add a description.

  3. Select Properties. The Object Properties dialog appears (see Figure 32.5).

  4. Enter a description in the Description text box.

  5. Click OK. The description that you entered appears in the Database window (see Figure 32.6), and it also appears in the output from the Database Documentor.


Figure 32.5. The Object Properties dialog can be used to document each object in the database.


Figure 32.6. The Database window with a description of a form.

Documenting Your Reports

Reports are documented in exactly the same manner as forms are documented. Reports have a Description property that must be entered from the Object Properties dialog. Remember that to access this dialog, you right-click on the object within the Database window and then select properties.

Documenting Your Macros

Macros can be documented in significantly more detail than forms and reports. Each individual line of the macro can be documented. This is illustrated in Figure 32.7. Not only does this provide documentation within the Database Documentor, macro comments become code comments when you convert a macro to a Visual Basic module. In addition to documenting each line of a macro, you can also add a description to the macro. As with forms and reports, to accomplish this, right-click on the macro from the Database window and select properties.


Figure 32.7. Documenting a macro by including a description of what each line of the macro does.

Documenting Your Modules

I cannot emphasize enough how important it is to document your modules. This is accomplished using comments. Of course, not every line of code needs to be documented. I document all areas of my code that I feel are not self-explanatory. Comments assist me when I revisit the code to make modifications and enhancements. They also assist anyone who will ever be responsible for maintaining my code. Finally, they provide the user with documentation about what my application is doing. Comments print with your code modules, as illustrated later in this chapter, in the section "The Database Documentor." As with the other objects, you can right-click on a module to assign a description to the module.

Using Database Properties to Document the Overall Database

In addition to enabling you to assign descriptions to the objects within the database, Microsoft Access enables you to document the database as a whole. This is accomplished by filling in the information included in the Database Properties window. To access a database's properties, select File|Database Properties or right-click the title bar of the Database window and select Database Properties. The Database Properties dialog is pictured in Figure 32.8. The Database Properties dialog is a tabbed dialog. The tabs include General, Summary, Statistics, Contents, and Custom.


Figure 32.8. The Database Properties window showing the General properties of a database.

The following is a list of the tabs of the Database Properties dialog and a description of what they contain:


Figure 32.9. The Summary tab of the Database Properties window.


Figure 32.10. The Contents tab of the Database Properties window.

The Database Documentor

The Database Documentor is an elegant tool that is part of the Access application. It enables you to selectively produce varying levels of documentation for each of the objects within your database. Here's how it works:

  1. Make sure that the Database window is the active window.

  2. Select Tools|Analyze|Documentor. The Database Documentor dialog appears (see Figure 32.11).

  3. Use the Object Type drop-down to select the type of object that you want to document.

  4. Click the check box to the left of each object that you want to document. You can use the Select All command button to select all objects of the selected type.

  5. Click the Options button to refine the level of detail that is provided for each object. Depending on which object type was selected, different options are displayed. Database Documentor options are covered later in this chapter, in the "Documentor Options" section.

  6. Repeat steps 3 through 5 to select all database objects that you want to document.

  7. Click OK when you are ready to produce the documentation.


Figure 32.11. The Database Documentor dialog allows you to designate which objects you want to document.

After you have selected all of the desired objects and options and have clicked OK, the Object Definition window appears. This Print Preview window allows you to view the documentation output for the objects that you selected (see Figure 32.12). This Print Preview window is just like any other Print Preview window. You can view each page of the documentation and can send the documentation to the printer.


Figure 32.12. The Object Definition Print Preview window.

Documentor Options

By default, the Database Documentator outputs a huge volume of information for each object that is selected. For example, each control on a form is documented, including every property of the control. It is easy to produce 50 pages of documentation for a couple of database objects. Besides being a tremendous waste of paper, this volume of information is overwhelming to look at. Fortunately, you can refine the level of detail that is provided by the documentor for each category of object that you are documenting. This is accomplished using the Options button of the Database Documentor dialog.

The Table Definition options are pictured in Figure 32.13. Notice that you can specify whether you want to print table Properties, Relationships, and Permissions by User and Group. You can also indicate the level of detail that you want to display for each field: Nothing; Names, Data Types, and Sizes; or Names, Data Types, Sizes, and Properties. For table indexes, you can opt to include Nothing; Names and Fields; or Names, Fields, and Properties.


Figure 32.13. The Print Table Definition dialog enables you to designate which aspects of a table's definition are documented.

If you select Queries from the Object Type drop-down and then click options, the Print Query Definition dialog appears (see Figure 32.14). The Print Query Definition enables you to select the level of detail to be output for the selected queries. You can opt whether or not to include Properties, SQL, Parameters, Relationships, and Permissions by User and Group for the Query. You can also select the level of detail you will include for each column of the query and for the indexes involved in the query.


Figure 32.14. The Print Query Definition dialog enables you to designate which aspects of a query's definition are documented.

The Form and Report options are similar to one another. The Print Form Definition dialog is pictured in Figure 32.15. It lets you specify whether you want to print Properties, Code, and Permissions by User and Group for the form. For each control on the form, you can opt to print nothing, the names of the controls, or the names of the controls and their properties. The Print Report Definition dialog offers the same options.


Figure 32.15. The Print Form Definition dialog enables you to designate which aspects of a form's definition are documented.

For macros, you can select whether you want to view macro Properties, Actions, and Arguments, and Permissions by User and Group. For modules, you can opt to view Properties, Code, and Permissions by User and Group.

As you can see, the Database Documentor offers you much flexibility in the level of detail that it provides. Of course, if you haven't filled in the properties of an object (for example, the Description), it does you no good to display the properties.

Producing Documentation in Other Formats

After you have produced the documentation and it appears in the Object Definition Print Preview window, you can output it to other formats. To do this, select File|Output To from the Print Preview window. The Output To dialog appears (see Figure 32.16). Notice that you can output the documentation to Microsoft Excel, to a Rich Text Format file, or to an MS-DOS text file. After selecting the desired format, click OK. Access prompts you for a name for the new file. It then proceeds to create the file and even launches you into the appropriate application based on the file format that you select: Excel if you select Excel, Word if you select Rich Text Format, and Notepad if you select MS-DOS Text.


Figure 32.16. The File Output To dialog enables you to designate the type of file to which the object definition is output.

Writing Code to Create Your Own Documentation

Most of the time, what is provided by the Database Documentor is sufficient. At times, you won't like the format that the Database Documentor selects—or more importantly, you might want to document properties of the database objects not available through the user interface. It is in these situations that you can opt to enumerate the database objects using code and output them to a custom report format.

Using Code to Enumerate the Objects in the Database

Using Data Access Objects, you can enumerate any of the objects within your database. The following is an example:

Sub EnumerateTables()
   Dim db As DATABASE
   Dim tdf As TableDef
   Dim fld As Field
   Dim fSystem As Boolean
   Dim fAttached As Boolean
   Set db = CurrentDb
   DoCmd.SetWarnings False
   For Each tdf In db.TableDefs
      fSystem = tdf.Attributes And dbSystemObject
      fAttached = tdf.Attributes And dbAttachedTable
      DoCmd.RunSQL "INSERT INTO tblTableDoc" _
            & "(TableName, DateCreated, LastModified, " _
            & "SystemObj, AttachedTable ) " _
            & "Values (""" & tdf.Name & """, #" _
            & tdf.DateCreated & "#, #" _
            & tdf.LastUpdated & "#, " _
            & fSystem & ", " & fAttached & ")"
   Next tdf
   DoCmd.SetWarnings True
End Sub

The EnumerateTables routine, found within the basDocument module of CHAP32EX.MDB on your sample code CD, documents various information about the tables in the database. It uses a For..Each loop to loop through all of the table definitions in the database. For each table in the TableDefs collection, it determines whether the table is a system table or a linked table. It then executes a SQL statement, inserting all of the requested information about the table definition into a table called tblTableDoc. This table could then be used as the foundation for a report. Of course, when you use appropriate For..Each loops and properties, any information about any of the objects in the database can be obtained using the same technique.

Applying What You Have Learned to the Time and Billing Application

Practice producing various levels of documentation for the Time and Billing application. Change the Options for each object type and view the difference in the results that each produces. If you are particularly ambitious, try writing some DAO code to enumerate the objects of the database.

Summary

Documentation is a necessary part of the application development process. Fortunately, Microsoft Access makes it very easy for you to complete the documentation process. This chapter covered the object Description properties that Access provides, as well as the extremely powerful Database Documentor. The chapter also highlighted how you can create your own documentation using Data Access Objects and custom reports. Using any combination of the techniques covered in the chapter, you can produce very complete documentation for all aspects of your application.

Previous Page TOC Index Next Page Home