When it comes time to make a change to your program (and you’ll have to change your program), good documentation can direct you to the areas to change and alert you to potential problems. If you have a bug to fix, effective documentation can help you solve the problem (without introducing new problems). Dennis Schumaker discusses the secrets behind creating useful documentation efficiently based on his company’s real-world experience in delivering Access applications.

One of the tasks that every programmer gets involved with, but hates doing, is writing documentation. Part of the problem is that many programmers view documentation as a one-time task, done at the end of a development project. A better attitude is to think of documentation as a series of smaller tasks, done throughout the project. Not only is it easier to develop documentation in small pieces throughout a development project, but it’s also easier to manage the project using this documentation. This article discusses the approach that we use at our company in creating documentation “as we go” on Access projects. The result is a documentation set that’s actually useful while being created as efficiently as possible.

Documentation philosophy

To a programmer, documentation could be defined as all the written material aside from the actual code that needs to be created either in relation to or as part of designing and managing the development project. There are several primary types of documentation that are part of a programming project. Our classification scheme divides documents into three categories:

• Managing the contract for performing the development project
• Using the application, which also is used to help design the application
• Setup and troubleshooting of the application, designed for technical support staff

None of these items is “documentation for documentation’s sake.”

In situations where a programming organization is developing an application on some type of fixed-price or “at risk” contractual relationship, the level of contract-management documentation required to successfully manage the contractual items will be significantly higher. Such documentation must, at a minimum, include:

• Commitments made in terms of the scope of the project
• Functionality of the application
• Responsibility for data conversion
• Final deliverables
• Detailed information regarding project schedules and budgets

Under this type of contract, the analysis work papers and other documentation that’s created and maintained throughout the development effort serves more of a purpose than just working out the details of the application. This documentation also details how you’ll be paid. The documentation allows you to determine what you need to do to get paid and may be the evidence that you provide to prove that you should be paid. However, the level of documentation that needs to be developed in these situations goes beyond what I’m going to discuss in this article. I’ll assume that compensation is based on “hours worked” rather than “products delivered.”

Another purpose of documentation is to provide a level of management of the whole development process. I once read that the actual time spent coding an application was less than 30 percent of the total project. However, our experience on smaller Access applications is that our buyers want to spend their dollars only on the “coding.” They either don’t understand or don’t appreciate the other 70 percent of the effort. “Faster, better, and cheaper” is what they like to hear. That usually means that we don’t have the budget or the time to spend analyzing their business processes or scoping out the design of the application before we start writing code. The sooner we can begin to show the client a working prototype of an application, the more likely they’ll be willing to proceed with the complete development. We do development only on a time-and-materials basis when using this type of development process. However, we still build documentation into our development process, because we’ve found that helps us manage the design and development process with our clients, helps us manage the interface with our clients, and can also lead to additional business in the long run.

The last type of documentation that I listed we call “technical.” It’s designed not for the user or the developer, but for anyone who must install, configure, and support the software. It can include such items as installation instructions, details on components necessary for the application to run properly, troubleshooting guides, file locations, customization instructions, and architecture notes. Such documentation is particularly important for companies who have separate staffs for development and implementation/support because it facilitates the transfer of expertise from the developers to the support staff (an often-overlooked phase of the development cycle). It also helps to keep the knowledge base of the company intact in the case of staff turnover.

Within the software development industry, we’ve found that there are two extreme, opposing points of view with respect to documentation:

• Good software shouldn’t require documentation! The software has been developed to such a standard of perfection that no system documentation or user documentation of any kind is required. Users find that using the application is intuitively obvious. The data model and code have been written in such a way that 1) it won’t require any maintenance or enhancements, and 2) the system is self-documenting.
• Good software must be carefully designed through a process that creates extensive written documentation! The software can’t be developed until we’ve performed an extensive analysis of the users’ business needs. Good software can’t be developed unless business process flow diagrams, function hierarchy diagrams, system/subsystem flow diagrams, database schema, and entity relationship diagrams are developed up front. Extensive user and system documentation needs to be developed at the end of the development effort for the software to be acceptable.

As with all extreme positions, the best practices are usually found somewhere between the two extremes. Large, complex systems that interface to a disparate collection of other systems will require the development of more extensive documentation before the programming can even begin. However, a smaller application and, more specifically, the types of systems that are typically developed in an Access environment can usually be developed with significantly less written documentation. In fact, it may be the case that the project budget doesn’t allow for much documentation—that is, if those costs had to be included in the overall budget, the client couldn’t afford to do the development. So the dilemma that we face as Access programmers is how much can we afford (or afford not) to develop documentation for our applications.

What are you trying to do?

The first question that you need to answer in formulating your documentation standards is: “What are your documentation objectives?” Our objectives are:

• Support the overall development process: We should be able to develop our applications faster, better, and cheaper using this level of documentation. We should also be better able to manage our applications development process.
• Facilitate communications with our client: Whatever we develop as documentation should be usable and readily understandable by our client. With the exception of business process flow diagrams, most diagrams (for example, function hierarchy diagrams, system/subsystem flow diagrams, database schema, and entity relationship diagrams) are typically more detail than our clients would like to receive. A rough prototype of screens and reports is much more useful in working with our clients than any of the “computer-programmer-savvy” tools mentioned earlier.
• Evolve into a product that can be left with the client, satisfying the need for user or system documentation: We don’t want to begin writing the user and system documentation near the end of the project, but, rather, to be writing the documentation all through the development process.
• Don’t use anything but “off-the-shelf” tools: Our documentation process shouldn’t use any third-party tools that are overly complicated or expensive. The learning curve for using documentation tools should be very short and, ideally, already in the programmer’s knowledge base. We don’t want to spend any more of our money on documentation than we need to in order to deliver an effective solution to our client’s problem.
• Support change: While it would be nice if we could put a development team together and have it stay together, that often doesn’t happen. People arrive and leave—we need to be able to maintain our productivity level through these changes.

Tools and process

What we’ve developed is a set of “off-the-shelf” tools and a development process that meets the preceding objectives. Over the course of many application development projects, these documentation tools and the development process have permitted us to design in a faster, better, and cheaper manner. And, almost as importantly, they’ve permitted us to move new programmers into and out of a development effort without any loss in productivity.

Documentation tools

The tools that our documentation process is based on are summarized here:

• User interface standards: We’ve developed written user interface standards to which all our applications conform. The beauty of these standards is that they’ve been documented in our programming standards guide and don’t need to be written up on a project-by-project basis.
• Development environment standards: This is an area that’s frequently overlooked by the one- or two-person development shop. It addresses such items as “Where on the server do we locate the latest code file? Will we be using source code controls? Where will we maintain any written documentation on our application? Where will the screen captures be located?” The need for this type of organization becomes more apparent when you move new programmers into and out of an application development project. If these development environment standards don’t exist, the manner in which these activities are performed on each development project will need to be explained to the programmer each time.
• Word processing standards: Almost all of our documentation is developed using standard word processing software (Microsoft Word, to be specific). We’ve modified Word’s toolbars and other features to accommodate the development of the types of documentation that are discussed in this article. This qualifies as an off-the-shelf modified documentation tool that I’ll discuss in more detail later in this article.
• Screen capture standards: One of the major ways that we document our development process is through screen captures. These screen captures, primarily of forms and reports, are used to communicate with our client and further assist in the design of the application.
• Coding standards and naming conventions: If you don’t adopt some type of coding and naming conventions, you can’t even begin to document your application. We’ve adopted naming conventions that are fairly standard through the industry.

These tools are used throughout our system development process (discussed next) to meet our documentation objectives.

System development

Although there have been many books written on system development processes, in most cases those books deal with the development of very large systems. Access applications are generally much smaller in size, although they can be just as critical to that smaller client as a larger system is to a larger client. The Access client is typically spending less than $100,000—and more likely wants to spend less than $50,000 (or even much less). At that level, the developer needs to get to a final working product much quicker than if the budget were $500,000-plus. In our experience, the sooner you can show the client a working prototype, the greater the likelihood that they’ll be interested in completing the project.

We therefore divide our development process into four phases:

• Napkin Phase: This phase took its name from the concept that some of the biggest ideas start out sketched on napkins. Through preliminary meetings with the client, we begin to sketch out some basic screen layouts for the primary business processes and the expected reports or other analyses that the application is intended to perform. We should be able to determine the number and type of different screens (Access Forms) that will be required for the business process and get a rough idea of the type of reports that will be required. Back at the office, we’ll sketch out the data model (tables and relationships) and start building the forms and tables and possibly some rough reports. Since we’re not talking about a fixed-price development project, the napkins don’t need to be retained after the initial screens and table design have been created.
• Screen Capture Phase: The rough application that’s developed as a result of the Napkin Phase is documented via screen captures. In essence, the Napkin Phase is complete when we’ve developed enough of an application that we can begin to demonstrate some basic functionality in terms of the forms and reports. Screen captures of each important form and report are created and pasted into a Word document for review and discussion with the client. Through various iterations with the client, we continue to develop the application into a working application. We also begin to address data conversion, both for application testing and downstream for the final conversion and placing of the application into production.
• Table Rules Phase: At some point in the development, it becomes more important to start “nailing down” the business rules for the main business process forms. At this time, in addition to the screen captures, we begin to insert Word tables into the documentation that we use in meetings with the client to “flush out” the actual business rules or calculations that apply throughout the application. These tables are discussed later in this article. During this phase we also begin to identify all of the application maintenance forms and other support processes that are needed for maintaining the application on an ongoing basis. Through various iterations with the client, we continue to develop the application.
• Completion Phase: The documentation that’s been developed is converted into basic user documentation by adding written discussions of the operation of the various forms and reports. Depending on the client’s needs and budget, more or less time might be spent on this activity.

In essence, the documentation that was originally designed on the back of a napkin eventually evolves into some form of user documentation when the application is finally delivered. This process has integrated into it some specific tools that are used through each phase to manage the development efforts.

User interface

All of our applications are designed using a very similar user interface, so there’s less that needs to be documented in order for the programmers to build the application and less that needs to be described in the written user documentation. In fact, we’ve found that we can often copy (editing and augmenting as appropriate) some of the text used in user documentation from other applications to meet the needs of current applications. I’ve discussed the standards that we follow in earlier articles in Smart Access.

Development environment

A standard operating procedure that usually evolves during the course of a programming effort is how to organize development projects on your computer or your network. If you’re like most single developers, when you start a project, you hardly give it any thought. However, as more programmers and other technical people get involved in the project, standards for how development projects are organized on your computer network begin to become more and more important. You eventually realize that:

• You need to really think through the organization.
• No matter what decisions you make on how to organize the files, everyone working on the project must know the organization and adhere to it.

We divide our file organization into two areas:

• Source and data files and other information used in creating the application
• Documentation that’s developed (that eventually evolves into the user documentation)

We’ve created a directory under a file share called “Development” on our network server. In this share, each individual application has a directory (see Figure 1). All of the various versions of the code and data files are maintained within that directory. In addition, any notes, data downloads from the client, and other information used to develop the application are held in that directory. This practice is slightly modified if the application is large enough that we’ve decided to use source code control (such as Visual SourceSafe). In that case, we have a separate directory where all of the code and data files are stored during development.

The documentation that we develop throughout the project is maintained at a separate location on our network. Each portion of the documentation for the applications is maintained within its own individual directory as shown in Figure 2.

Part of the reasoning behind this separation is that only the programmers have access to the Development share, whereas the Document share (where all the documentation is kept) is also accessible by non-programming personnel (for instance, our consultants, business analysts, and technical editors).

The documentation is organized into individual files (one for each chapter). You’ll note that the individual files correspond to our user interface standards in that there are separate files for each area of the application. We use Microsoft Word’s master document feature (which is implemented in the Master Manual.doc shown in Figure 2) to electronically merge the individual chapters together at any time throughout the development project into one document (Media Manual.doc). From that document, we can create tables of contents and exhibits and print out all of the documentation together in one document. We find that it’s beneficial to pull this information together into one document periodically throughout a project and share the document with our clients as part of the development process.

Screen captures that are used within the documentation are maintained in separate directories (one or more by chapter). As changes are made in the application, new screen captures are created and inserted into the documentation.

Coding and naming

Strict adherence to programming standards is the closest that you can get to making the application self-documenting. Programming standards are essential to application development and are used in formal multi-programmer shops. These standards assist programmers in creating a uniform structure, coding style, and logic for an application and help our programmers create unambiguous, simple-to-read code that’s easily maintained by other programmers in the organization. Coding and naming standards reduce maintenance costs through consistency and permit the easy transition of our programmers from one project to another. Even if another programmer wrote the code, you can immediately read new code and understand it.

Our standards are based on a version of the Hungarian convention, the Reddick VBA Naming Conventions. We’ve developed our own written standards manual (liberally borrowing from those who have preceded us) and enforce the manual by in-house code reviews throughout the development project. On occasion we’ve also brought in outside consultants to assist in this part of the project.

Word processing standards

Because we’re a management consulting firm, we didn’t do application development when we first started business. We eventually added that service as our own business needs and our clients’ business needs dictated. Both at the start and today, we’ve written and continue to write fairly extensive proposals to win work and the reports that are the final deliverable on our consulting projects. We typically compete against much larger firms, including those firms that were at one time referred to as the Big 8, then the Big 6, and so forth. Our competition typically has a proposal-writing group, word processing area, or some other focused group whose sole purpose is to write and/or edit proposals and reports. Our size doesn’t permit us to commit to such resources, so we have to rely on the 10 fingers of all our consultants to do the word processing. We augment our own abilities with extensive Microsoft Word automation (templates, styles, AutoText, macros, and forms) to streamline our process in order to effectively compete against the “bigger guys.” The long and the short of this discussion is that we’ve developed an extensive set of Word tools for our proposals and reports that support writing documentation for our development projects.

Toolbars and templates

We’ve added functionality to Microsoft Word to support the documentation that we create (manuals, proposals, reports, and so on). Our standard interface screen to Word is shown in Figure 3. We’ve added two toolbars to Microsoft Word that contain features used in creating our documentation: the Report Toolbar (Figure 4) and the Editor Toolbar (Figure 5).

The Report Toolbar contains the Exhibit button that’s used to insert an AutoText item that we paste our screen capture exhibits into. The exhibit AutoText has the appropriate formatting and line spacing and is designed so that a Table of Exhibits can be created using Word’s built-in features. In addition, the ExhibitCrossReference button is used to insert a cross-reference in the text (when the text is finally written). In this way, as new exhibits are added or removed, the renumbering is automatic.

We’ve developed several macros that support our documentation and can be called from the Editor Toolbar. We use the master document features of Microsoft Word to electronically combine all of the individual chapters into one document. The MakeOneDoc button runs code that will create a new document from the master document. Then chapter numbering is applied using the AddNumbering button, and a Table of Contents and Table of Exhibits can be created from the combined document. Using these tools, we’re able to combine and generate tables of contents and exhibits for a 300-page document in less than five minutes.

We also have created an AutoText term that permits our programmers to insert a Word table. Usually during the Screen Capture or Table Rules phase of our development projects, we find it necessary to develop more documentation on exactly how the key business process forms and reports are to function. The items in Table 1 serve as the starting point for flushing out those details with our clients.

Table 1. Tables used to define the client interviews.

Third-party tools

Although one of our stated documentation objectives is to not use third-party solutions, there are two applications that we found beneficial that have been incorporated into our documentation standards. The first must-have tool is software that will permit the printing of all our VBA code in a readable, organized manner. Granted the code can be printed with Microsoft Access or Word, but it’s not organized or readable. We use a product named VBACodePrint (it costs about $30-$50 over the Internet) for printing our code. It organizes the code by providing a Table of Contents to all the classes (including forms and reports) and standard modules. It then prints the code with bolding for comments, lines showing all of the logical loops, and other features, all of which are user-configurable. There are probably several other applications available on the Internet that will do essentially the same thing.

The second third-party tool that’s a necessity for Access development is Total Access Analyzer from FMS, Inc., which provides comprehensive documentation and analysis of Access objects (we also use several of FMS’s other tools). We start applications by translating our user requirements directly into a prototype application in Microsoft Access. We then use FMS software to develop the function hierarchy diagrams, system/subsystem flow diagrams, database schema, and entity relationship diagrams from the prototype. Using Access, we further develop the table structure and table relationships, prototype all data entry forms and reports, and develop many of the business rules for the system. Effectively, we use Access as our design tool and Total Access Analyzer to print out the results. Documentation is generated for tables, fields, indexes, relationships, queries, forms, reports, controls, macros, command bars, users, groups, security, and more. The documentation can be viewed and searched using a tree view display or printed using any of the program’s 220 reports. Because the output is stored in Access tables, the data can be queried and exported for further analysis.

We take screen captures of the prototype screens and write narrative design documentation in the cases where the output of Total Access Analyzer is insufficient to document the system design (primarily in the area of specific business rules). These documents serve as the basis for ongoing meetings with our client to validate the system design.

Screen captures

One of the most important pieces of software that you’ll need is a screen-capture program that gives you the ability to edit and modify your screen captures. In many instances, you won’t want to capture the whole screen but only one object, one toolbar, or a button on a toolbar. You can either capture a larger picture and cut out what you don’t need or use a utility that captures just what you need. We use Paint Shop Pro, a complete painting program, for this, although there are several other tools that could be used. Captureze is only a screen capture program, but it allows you to capture just a section of the screen or a single object.

Screen captures are inserted into Word documents within the exhibit frames, which are inserted using the toolbar buttons previously discussed. We use Word as the repository for our graphics because:

• It’s much easier to manage the documentation as files containing multiple related screen captures than to handle individual screen capture files that must be printed individually and collated to organize.
• We can use the master document features of Word to pull together the individual Word files into a complete document for easier printing and organization.
• Using the exhibit template that we’ve inserted, we can easily generate a complete table of contents and table of exhibits (essentially a table of screen captures) to assist us in organizing our thoughts.

This document also serves as a communication tool to use with the client to “nail down” the design of the application. It also serves as a good tool for taking notes about the changes that need to be made to the application as a result of meetings with the client.

We’ve found that very real and tangible benefits result from integrating the development of documentation into the process of designing and developing Access applications. This approach might not be as rigorous or complex as those used on development projects for larger systems; however, it’s been our experience that it works well for the majority of application development projects that Access developers might undertake. By using this approach, our design and development projects run more smoothly, and we’re able to meet our internal objectives as well as our clients’ objectives of “faster, better, and cheaper.” Furthermore, if there’s any ongoing or future maintenance that needs to be performed, it will be much easier to come up to speed on an application that has documentation that was written in tight integration with the application development process.

It’s important to note that this “faster, better, and cheaper” approach doesn’t mean that the developer will make less money creating the application. Due to the inherent efficiency of the process and the capability for replicating it on future projects, we’ve found that our profitability is higher than before we applied these processes and standards. Moreover, the sooner the client recognizes a benefit from the application, the more likely it is that they’ll to want to “enhance” the application or consider the development of additional applications to improve other business functions of their organization. And that generates more business for us.