Appendix B

Design Specifications: A Detailed Outline


This appendix expands on the specification outline that is included in Chapter 4, "Creating Design Specifications," and on the CD-ROM as file SPECSHEL.DOC. Here, I provide helpful details about the suggested contents of each specification topic in the outline.

Different specifications will have different layouts, depending on the responsible personnel and the needs of each project. The flow of my example is only a suggestion to guide your specification process-there is no single "correct" outline for a spec document.

Many people working on an Access application of any size fail to predict the complexities of development, testing, budgeting, and deployment. Even if your project is too small or your timeline too tight to allow for a specification as detailed as this outline, reading through the outline before you begin your project will help alert you to the many facets of development and deployment.

For purposes of this specification outline, I use the term section to refer to a major segment of the document. Within sections are subsections, and each subsection has several topics that describe individual discussion points.

1. Executive Summary

An "Executive Summary" section is a common requirement for business documents. In a specification, this is probably the only section that executives at the program manager level and above will read. Its purpose is to provide a clear, accurate, and concise synopsis of the project by highlighting the project's functionality, justification, and cost.

As a general rule, writers of business documents try to keep the "Executive Summary" to one or two pages. For a specification, the reality is that one page is impossible, two is desirable, and three or more is commonplace.

1A. Overview

The first portion of the "Executive Summary" section presents an overview of the software project by summarizing the problems it addresses and the methodology that will be employed.

Identified Problems

This component of the "Executive Summary" section provides a few paragraphs or bulleted list items that summarize the problems or opportunities within the company that pointed to the need for the solution described in the spec. The text here need not identify all specific problems or needs but should at least describe the ones that will be used as a basis for the cost justification topic later in the summary.

Proposed Solution

This topic briefly describes the proposed solution and how it will achieve the objectives itemized in the previous topic. These paragraphs should note who in the company will be affected by the project and what the expected effect on their daily workflow will be.

Project Scope

In this topic, provide a brief description of the scope of the project, including some or all of the following points:

1B. Justification

This subsection is essentially the "sales pitch" targeted at the readers that will be involved in approving funding for the project.

Cost Justification

In this paragraph, answer the question "Why should the company spend money on this project?" as succinctly as possible. Usually, the justification highlights one or more of the following benefits:

Return on Investment

In some projects, the specific financial benefits of a project can be favorably contrasted to its costs, which provides a calculation called return on investment (ROI). The ROI usually quantifies the payback period of the project in months or the total return over the life of the project. If the increased revenues or decreased expenses from your project can be quantified, include a paragraph in this topic and possibly a table or graph for clarification.

Computing the Return

It may not always be easy to tally a solution's positive economic impact on the company because you must measure both the benefits of the solution and the costs of the problems it solved.

The benefit of automating a process, for example, cannot easily be measured if the process is new because no historical benchmarks exist yet. At the other end of the spectrum, the human resource overhead for a process that has existed in the workflow for a long time can be measured exactly. When automation is applied, the time savings can be quantified and the positive impact of the application computed.

For example, one of our clients recently asked us to provide a simple database application to replace a process by which employees capture customer information into a spreadsheet. The client interviewed all 150 employees involved in the process and found that they spent an average of eight hours per week, or 32 hours per month, logging the customer information.

We helped the client design a database to capture the information more effectively, and the users on the design team were able to estimate that the new system would cut their time managing the customer data by three hours each week. The client was then able to place this justification in our spec:

Current Process

New Process

Hours Per Month Consumed

32

20

Times: # of Employees

150

150

Times: Hourly Burden

$40

$40

Equals: Monthly Cost

$192,000

$120,000

Monthly Savings

$72,000

Because the application we created was quite simple, its cost was returned to the client in the first week of use, leading my employees to joke that we should change our billing model from hourly rates to taking a percentage of the money saved by our clients when using our applications!

1C. Resource Requirements

In the introduction to this third subsection of the "Executive Summary," summarize the actual resources that will be consumed by the project. The cost of a project is not only measured in direct cash outlays-there are other company assets that are used to create and deploy an automated solution.

The costing items summarized here and described in the following three topics must total to the project cost number used in the "Return on Investment" topic earlier in the spec. Later in the spec (in "Costing"), a line-item budget is provided, so this topic exists to "hit the high points" for busy managers.

Human Resources

In this topic, detail the human capital that will be expended to create the application. Human capital is measured in time increments and in the cost of that time to the company. Include the cost of time spent by design team members, users, management personnel, developers, contract coders, testers, trainers, and support personnel.

Some companies also measure opportunity cost when computing the expenditure for a project. This measurement assumes that, while people are working on the project described in the specification, there are other projects that they are not working on. Thus, the gains on the automation project are offset to some extent by the losses on the neglected efforts.

Physical Resources

Automation projects also consume physical resources. The most common physical resources used by an application are the storage space on workstation and server disks, and the wear and tear on the computers developing and running the application. While storage space is sometimes hard to price, in some cases an application may usurp an entire server for itself, the cost of which is known.

Other physical resources consumed by an application development project include: the overhead of contract programmers onsite or staff developers working overtime (extra electricity, food, or equipment that will be consumed); intangibles like printer paper; the use of corporate meeting facilities and training equipment; and rented furnishings or overflow office space. Such resource consumption is often difficult to quantify, and most companies elect not to try to measure these costs in a spec unless they are unusually large for the specific project.

Capital Resources

This topic details the items that will require a cash outlay during the project that are not included in the two previous topics. Usually, capital expenses are those that involve the purchase of tangible assets, such as the upgrade or purchase of software tools or applications, server machines, workstations, network hardware, modems, printers, and other infrastructure items to support the application.

2. Application Processes

This major section of the spec document describes the solution from a functional standpoint. It includes descriptions of the following:

2A. Solution Description

This subsection is usually a lengthy, matter-of-fact description of the project and varies greatly by project. It often includes topics for solution mechanics, system architecture, user interaction, primary objects, flow of data items, and similar subjects.

This section usually describes the current workflow in the process to be automated and the changes to the workflow that will be introduced by the new system. Process flow diagrams of the current or proposed workflow may be used to clarify this information.

2B. Primary Processes

This subsection provides a technical description of the primary logic (code) processes in the system. Logic processes in database applications include such routines as the following:

The process descriptions in this subsection constitute actual instructions to the programming team, and should be completely explicit. In some cases, numbered (stepped) lists are adequate; in others, the design team should write pseudocode to describe the process in detail. (See Chapter 11, "Expert Approaches to VBA," for information on writing pseudocode.)

2C. Application Navigation

This subsection describes how users will interact with the application's interface.

Setup

Describe here the requirements of the setup program or installation routine. Detail the components to be installed on the users workstation, special setup logic requirements, version or license control issues, and so on.

Launching the Application

The specification should describe here how users will start the application. For example, the application icon and its label, the window caption, and the command-line arguments should be provided for shortcuts that will point to the application, if appropriate. Include relevant login or security information.

Interface Philosophy

This topic describes the pervasive interface approaches that will affect how users move within the application. Include in this topic information on using the runtime, object security, and application bulletproofing techniques to move users between application objects and to restrict the availability of the built-in features of Access (techniques for bulletproofing are described in Chapter 17, "Bulletproofing Your Application Interface"). Also discuss here the standard menu, toolbar, and other navigation metaphors to be used in the application.

This topic is for discussion of general strategies-specific information about interface look-and-feel goes in the "Screen Forms" section later in the spec.

Navigation Map

In this topic, I create a navigation map of the application, which is a flow diagram of a user's interaction with the forms and logic processes. We devised the navigation map concept to help the design team and prospective users review and approve the flow of the application, and it has proven popular on our projects. The diagram shows each form in the application and a visual depiction of how the user moves between the forms. See the section "Creating Database Diagrams" in Chapter 4, "Creating Design Specifications," for an example.

2D. Initial Data Conversion

Few applications are launched completely devoid of data. Instead, data is usually preloaded into an application from existing databases, worksheets, a retail application, or hard copy records.

This subsection of the spec details which tables get populated before the application's initial release and from where. The information here should be definitive enough that the development team can do the data loading based on instructions in the following topics.

Source of Initial Data

Include in the spec a matrix showing the tables that will be pre-populated, and the sources of the data for each. Describe the data source by file name, table and field names, or other specifics, and be sure to note any record selection/filtration clauses if not all records in an existing data source will be used. For example, when preloading records into a hospital patient information system, we were instructed to only import historical records from the mainframe for those patients that had visited the hospital more than one time in the past ten years.

This topic should provide specific instructions so a person can be dispatched to fetch all of the data that will be preloaded into the new system.

Converting and Validating Initial Data

Sometimes, pre-populating a database application involves more than simply pulling records from an old platform into the new one. Historical data may be formatted in a completely different fashion than the new structure requires and may involve complex conversion procedures. For example, we preloaded a client's application with data from thousands of e-mail messages containing communications from customers. The conversion of the messages from Microsoft Mail format into data records involved designing complex logic to "read" and analyze each mail message, and break its text into specific database table fields.

Use this topic of your spec document to detail the specific conversion algorithms to be used in data preloading and to map source data fields to their new destinations. Be sure to note validation rules that must be met by each historical data record before it can be loaded, and the logic to "clean up" the data to meet these rules. For example, we often create a table that shows the following information:

2E. Links to Other Systems

Few applications are an island with data captive to the system and not flowing from or to other systems or applications. Instead, data may be imported from, exported to, or otherwise linked with other systems. Use this subsection of the specification document to detail such requirements for your application.

Downloads

Describe here the type of data that will be pulled into the application from other systems. For example, we created an inventory control system for a food manufacturing company, and the system had to pull the current product pricing from the corporate AS/400 minicomputer each month before running our inventory processing routines. The description of the AS/400 export logic in this topic of our spec allowed us to easily coordinate the efforts of Information Technology personnel creating the download file.

Note in this topic the frequency of data downloads, the linkage mechanisms to the external data, and detail the import and validation logic to be used.

Uploads

It is almost as common for your applications to send data to other systems as to receive data from an external source. For example, a medical clinic billing system that we created must collect all patient transactions entered during the day, dial the phone each night, and send the transactions to an external billing vendor's computer, which produces invoices from the data.

In this topic, detail any similar requirements of your application to send data to other computer systems. Note the frequency of the exports, the validation to perform on the data before sending, the communication mechanism, and methods for reporting success or failure of the automated process to the users.

Import and export/upload validation logic usually includes summary records or values called checksums to confirm that all records were received accurately. A checksum is a unique number, usually created by totaling all of the values in a particular column in the data.

Merges and Links

In most PC database systems, and especially in Office-centric solutions, users will expect the application to help them merge some of the database information to other applications for the purpose of analysis or reporting. For us, one of the most dramatic changes we've seen in Access application development in the previous year is the surge in user requests to do reporting by sending data summaries to Excel. We create program code to format and populate a worksheet via Automation, and in some financial applications, this is the only reporting mechanism; there are no hard copy Access reports.

If your application will help users merge data to Word, Excel, PowerPoint, the Web, or any other destinations, note the requirements for such features in this topic of the spec.

2F. Security Requirements

If the application will be secured, detail here the security requirements and their enforcement mechanisms in the schema and UI.

Workgroup Security

This topic details the workgroups designated for the application. It should include a document table showing security groups and the users for each and describing the general purpose for each group and its place in the security hierarchy.

Application Security

In this topic, map the groups detailed in the previous topic to specific application objects and describe the permissions at the object level. Such a relationship is best represented by a table in the document.

If the application will use programmatic security rather than Access workgroups, describe the structure and code for such security.

2G. Multiuser Issues

The multiuser nature of the application is determined by the number of concurrent users expected and their anticipated data entry/edit behavior. Detail these expectations in this subsection of the spec document, and lay out the resolution mechanism for any problems that will accrue from the expected usage patterns.

Specifically, this subsection should describe the approach to be used in the application to resolve multiuser record write contention issues. Usually, the resolution is to decide between optimistic, pessimistic, and programmatic locking strategies and between bound and unbound data forms and to note specific development approaches to be used to apply the selected philosophy.

3. Project Mechanics and Management

This major section of the specification document describes how the project will be managed and delivered and clarifies issues that are relevant to the development team members and management personnel.

3A. Project Management Overview

As an introduction to the management section, note here the specific issues and concerns unique to this project and important to its managers and creators.

3B. Architecture and Tools

No specification is complete without a description of the toolset to be employed by the development team. This subsection notes technical information about the development environment.

Platform

The primary platform for an application is its operating system and development language, which should be noted in this part of the specification. In the case of Access applications, the development language actually includes all the various ingredients of Access: the Access interface, DDE, Jet, Automation (OLE), and VBA. Each of these components is a language tool to be used in creation of the solution.

Development Tools

Describe in this topic any other tools or extensions that will be employed in addition to the primary platform. For Access development, this often includes third-party tools for developers, add-ins (such as wizards), ActiveX controls, and similar extensions.

Reusable Components

You may recall that part of the specification research process includes locating existing components that can be reused in your application. Detail any such components here.

In the past, this topic has been rather sparse for Access applications, due to the difficulties of building and using Access-based components. With the concurrent release and shared language engine of Access 97 and Visual Basic 5, more development teams and product vendors will be creating reusable components for Access applications that are based on Visual Basic or at least VBA. These will take the form of code libraries, class objects, Automation servers, DLLs, and SDKs (Software Development Kits) shipped with unlocked source code.

3C. Equipment Requirements

The spec document must detail the hardware requirements dictated by the application.

Client Configuration

This topic notes the required configuration for client (user) workstations. Usually, a minimum configuration and a suggested (average) configuration are both described.

Configuration information should include hardware, software, peripheral, operating system, and driver details.

Server Requirements

The machine on which the data will reside should be described in this topic. If the hardware will be purchased specifically for this application, note the actual configuration requirements, preferred vendor, and any installation issues. If the application's data will reside on a shared server, name the server, the path for the data back end, security configurations, and any issues involved in sharing the server with other applications or databases.

Connectivity

Describe in this topic any special connectivity requirements for users of the application. Connectivity issues arise in one of the following areas:

Equipment Upgrades

This specification topic should name the user workstations that must be upgraded to comply with the configuration and connectivity requirements previously mentioned. Note here the complete list of required parts and labor per machine, the itemized cost of each, and the time and manpower schedule for the upgrades.

3-D. Application Deployment

Since the entire development project is focused on a "ship date," the spec must include implementation plans to guide the project team toward that date. This subsection provides information designed to help get the product (application) in the hands of the customers (users).

User Definition

Describe in this topic the users of the application. In widely deployed applications, the user base is described by department name, job title, workgroup, or other aggregate grouping. Users may even accrue to a system simply by virtue of the computer they use. Smaller user groups can be described by actually naming the users.

It is equally important here to describe users of the system more generally by their attributes. Note the skill level, physical location, workgroup membership, and other hurdles that users must leap to qualify to work with the application, both at deployment and in the future.

Review Builds

The most important early milestones in the development process are the prototype phases. Note in this topic how many application reviews are in the development cycle, what will be provided in each review build, and when they occur. Describe the users that will participate in each review and how the review process will work. You can communicate this information in a table like this:

Build

Features Included

Distribute To

User Interface Review



Working Model



Beta 1



Testing

The following three topics describe the procedures to be employed by those testing the application.

Unit Testing

Normally, the development team will test the application before user testing begins. Developers test discrete components (units) of the software as they are completed and then test how the components work together with other components. In this topic, describe the involvement of the development team in the testing process and the scheduling and verification of such efforts.

System Testing

Final testing is usually done through several releases in a cycle called system testing because the entire system is tested as if the application is complete. Describe here the expected test releases and their feature sets, when releases will occur, the composition of the test audience, the test audience, the feedback mechanisms for problem reporting and fixes, and any other issues related to widespread testing.

Test Plan

Specs for complex applications may include a detailed test plan here describing how to test each major feature of the solution. If the test plan is lengthy, it may be preferable to include it in the "Appendixes" section and reference its location here.

It is important to detail the users' testing commitment here in addition to that of developers. Users involved in testing need to be made to understand that their thorough testing is critical to the quality of the product, and their punctual testing is critical to the timely delivery of the product. Most users underestimate the amount of testing required to create a solid application.

Preloading Data

In subsection 2D of the specification, "Initial Data Conversion," a strategy was detailed for converting and loading history data into the application. That strategy was a mechanical one, whereas this topic is for describing the task in political terms. Historical data usually has ownership, security, and maintenance issues that involve multiple departments or groups of users. In this topic, clarify and resolve any such issues, and detail the resolution of such issues.

Training

Describe in this topic the user training plan for the application. At the least, note the following points:

Deployment

The deployment strategy for the application should be discussed in detail in this topic. The following issues should be defined clearly, along with the parties responsible for each issue:

Online Documentation

This topic should clearly describe the electronic documentation requirements for the system. If a Windows Help file, Multimedia Viewer file, intranet Web site, or other tool will be distributed to users, outline its organization and contents. Remember to also list the individuals involved in writing, editing, and testing the online documentation.

User Documentation

At this point, the specification should detail the requirements for producing hard copy documentation. If possible, provide an outline, target page count, and other parameters for the user documentation.

Sometimes your spec can reference an existing document from a previous project to use as a model, rather than providing detailed writer's guidelines here. Include the sample document as an "Appendix" item.

More and more developers, ourselves included, have adopted Microsoft's model of turning the hard copy documentation into the online documentation. If you utilize this strategy, you will take special pains when you organize and write user documentation so that it can easily be converted to a compiled Help file. You should note such documentation strategies here or reference a company style guide document so that the documentation writers can refer to the specification or elsewhere for guidance.

System Documentation

Each company, and development group, has its own standards for system documentation. Usually, a project of any modest size or larger is delivered with documentation on such elements as the following:

In this topic, include or refer to such system documentation elements. The documentation should list or diagram any information here that will be useful for sustaining the ongoing health of the data and its use. System documentation should provide an adequate road map for future developers to follow when diagnosing problems or designing enhancements.

Database Administration

In the previous topic, "System Documentation," I noted that you should detail the important procedures for system maintenance. The information presented in that topic provides a physical "map" to guide administrators through the database. This topic augments that information by describing the political components of database administration, which should include at least the following points. When writing the four topics below or your own additional topics, try to imagine that you were not involved in the creation of the database but rather inherited the day-to-day administration of it after deployment, and ask: "What information would I need to be successful in fulfilling such duties?"

Administrators

In this topic, note who will administer the database and what the scope of each person's responsibilities and authority will be.

Backup Policies

Note here the backup policies for the database back end, including backup times, responsible parties, and off-site storage plans. Describe resolution steps for "bumping" users from the application so that repairs, compacts, and backups can get exclusive locks on the data file(s).

Disaster Recovery

What are the disaster recovery policies for the application? In this topic, detail the recovery steps for the "worst case scenario," usually the destruction of the building in which the data server resides.

Adding Users

In this topic, describe how new users will be added to the system and who will determine their security levels.

Localization

The world keeps getting smaller, and design teams must often explore the ramifications of installing an application in a branch of the company outside of the country it was created in. If the design team comes up with recommendations or strategies for making the localization (translation) of the application easier, document those strategies in this topic along with any suggestions for transnational installation, configuration, training, export/legal issues, and documentation.

Ongoing Support

The spec should address not only the ongoing management of the database but the ongoing support of its users as well.

Supporting Users

This topic describes how users will be supported when they have questions. Note support mechanisms-for example, support by phone, e-mail, or in person-as well as designated support personnel and target turnaround times.

Reporting Problems and Enhancement Requests

Ideally, the company infrastructure provides a mechanism for users to report issues, problems, and suggestions generated as they interact with the application. This topic should detail such mechanisms and how they will be set up and maintained.

Problem/Enhancement Resolution Guidelines

Every user and developer wants issues (especially bugs) addressed immediately, but managers usually have to prioritize the issues for attention in order of importance, taking budgetary concerns into consideration. The policies and procedures for making such tradeoffs should be noted in this topic, as well as the expected staging for interim releases that address accumulated issues.

Future Releases

In addition to planning for interim builds (sometimes called maintenance releases) in the previous topic, the spec document should discuss expected major future development phases and releases. Some specs may actually detail future features in the current specification-as a result of forethought applied by the design team-and note the expected future phase in which each feature will be implemented. In other cases, this topic provides only a reference to the staging of future phases, with a notation of the timetable and procedure to be used to begin design work on each future phase.

3E. Project Management

This subsection of the specification lays out the details related to ongoing management of the project.

Affected Users and Related Parties

An application always has one or more direct (hands-on) users. There is usually also a "ring" of other people around this user group that are affected by the application (I call this "spillover"). This topic describes affected parties and how they will benefit from the application's calculations, reports, or other outputs, even if they are not direct users of the technology. Also define the alteration of the workflow of nonusers, the linking of data from this project to other systems, or the flow of data beyond the target user group.

Because not all people affected by technology are affected in a positive way, this topic should also address such areas as worker displacement or reassignment brought about by the solution. Note any political ramifications of the spillover and how these will be addressed.

Project Timelines

In this topic, note the definition of final delivery, including the specific components of the delivery:

Responsible Parties

Each of the major roles in the project must be delegated to individuals in the company or to contract resources. This topic should describe the parties involved in the project and their roles. Recall from Chapter 3, "Preparing for Development," that the project team includes people with the following responsibilities:

Project Administration

In this topic, describe more clearly the guidelines and techniques that will be employed by the project manager to ensure a timely and successful completion. Include a discussion of political issues such as scheduling of meetings, coordination of parties, lines of authority and accountability, and resolution of disputes within the project team.

Issue Management

Discuss in this topic what strategies will be used for managing open issues during development and measuring their completion. The spec should establish clear communication and feedback methods and even name tools and methodologies to be employed, where appropriate.

Risk Management

As part of a realistic approach to managing development, the spec should list the possible pitfalls and failure scenarios that may complicate the project. A strategy for dealing with the most likely or dangerous risks should be discussed by the design team, and then documented here.

Coding and Documentation Standards

In some applications, most frequently those that will be delivered to or maintained by a large corporation's IT personnel, development standards may be imposed upon the application development team. Any such standards or approaches related to coding policies, source code and version control, in-line documentation, team development, object management, naming conventions, and so forth should be described in this topic.

Future Phases

In the topic "Future Releases" in the subsection "Application Deployment," future releases of the application were described from the perspective of their features and functionality. In contrast, this topic notes items deferred to-or consciously planned for-future expansion, and discusses their managerial consequences, as follows:

3F. Financial Mechanics

This subsection provides the details to support the financial (costing) information provided earlier in the "Executive Summary" section.

Costing

Provide detailed cost breakdowns here, listed by phases, months, milestones, or other logical arrangement. Remember to include the cost of equipment upgrades, components and tools, training, and other nondevelopment outlays.

Third Parties

Use this spec topic to name the parties outside of the company that are involved in the development and deployment. Third-party vendors may be utilized to provide contract services for design, project management, program coding, testing, documentation authoring, equipment upgrades, or training. Each party should be listed, along with contact persons, scope of responsibility, and similar management information.

Contractual Issues

If any third-party labor is to be used in the course of the project, you may want to include here text describing the contractual or other legal relationship with each vendor. Note the contracting parties, the major contract elements, mechanisms for dispute resolution, and other legalities.

4. Data Structures and Rules

The first three main sections of the specification constituted the business issues and application processes portions of the document. Beginning with this section, the specification content moves from a managerial plane to a highly technical one.

This major section provides the blueprint for construction of the foundation elements of the database application: the data tables and the business rules for validating the data that they hold. Just as a house built on sand will settle and crack, an application built on an incomplete data structure or inaccurate data will quickly show signs of strain, so this is the area where I expend much time when creating a spec. The wishes of the users, as filtered through and clarified by the design team, are distilled from screen and report designs into table structure definitions here.

4A. Data Models and Diagrams

In this subsection, include any visual representations of the database schema (structure). At the simplest level, a graphical representation of the primary tables and their relationships is a common inclusion in this subsection. For more detailed specifications, structure diagrams called Entity Relationship diagrams and Object Role Model diagrams may be appropriate. If the diagrams are large or too awkward to place here, include them in the "Appendixes" section and reference their location here.

4B. Schema Definition

This subsection provides a place to document each facet of the database structure.

Table Structures

For each data table, include a listing in this topic of the table fields and their properties, including index information. The layout and depth of this information varies across different developers and projects. I prefer to build spreadsheets listing tables and fields and capturing the primary properties of both. This allows the design team a single document from which to actively discuss and clarify the fine points of the data structure. Some development groups believe that the development team is responsible for assigning properties to table structures and do not burden the design team with any details beyond the field names and sizes.

If the table structures can be expressed in tabular format in the spec document, include the tables here, or attach the hard copy layouts to the "Appendixes" section and reference their location here.

Stored Views

In SQL back-end databases, saved views (queries, in Access terminology) are used to provide concurrent access to data in multiple related tables. Most Access databases have several types of saved queries, each of which should be documented here as follows:

Table Relationships

In this topic, describe the relationships between the tables, how they will be created, and how data integrity between related records will be enforced.

Business Rules

Access provides some built-in mechanisms for data validation (such as the LimitToList and ValidationRule properties). Additionally, most applications include some programmatic data validation as well. Since the integrity of data is one of the paramount missions of both the back-end database and its application, validation criteria (called business rules) should be crafted by the design team in conjunction with the developers and documented in detail in the specification.

The information on relationships here should match the visual depiction of the database structure in the earlier "Data Models and Diagrams" section.

4C. Data Load

When building a database application, it is helpful for the development team to understand the quantities of users and data that the application and data structure must ultimately support. Such information assists the developers in performance tuning the application, load balancing, and addressing multiuser issues.

Initial Volumes

List in this topic facts about the initial load on the application, including the expected number of concurrent users, data transactions, and records for each table. Discuss also the quantity and quality of data to be preloaded from existing systems.

Future Volumes

This topic should provide tables or graphs to show how the user and data loads on the application will change over time. Note the same information as in the previous topic, projected at various time increments throughout the life of the project.

5. Screen Forms

The degree of form information included in the specification varies by project. Because much of an application's cost is in the forms, we have come over time to clarify the forms more and more tightly in this topic to avoid expensive reworks later in the project.

Recall that we placed the navigation map for moving between application forms in the "Application Processes" section earlier in the spec. That diagram fits just as well in this topic, if you prefer.

5A. UI Guidelines

In this subsection, note the standards and policies of the company or user group that will dictate the "look and feel" of the forms. For a better understanding of the various elements of a user interface, read Chapter 8, "Designing Effective Interfaces."

Form Layouts

Note here any standards for the layout of forms, such as the preferred location of buttons, the justification (left/right) of labels and other controls, the use of sunken versus flush or raised effects, whether MDI is allowed, and so forth.

System Messages

Describe in this topic any special considerations about how messages (alerts) should be displayed for users. For example, some applications make use of built-in Access error messages, while in others the developers try to make the messages more friendly and descriptive. Also, some companies put information about their HelpDesk or other technical support options in system messages or prescribe specific captions to be displayed in alert dialog boxes.

Fonts and Point Sizes

Note here the user interface standard to be followed by the development team for the use of fonts. A variety of issues crop up in this area, including the following:

It may also be wise to specify here the names of all fonts allowed in the application so that there is no danger that the developers will include a font in the application that is not installed on a user's workstation (a common Access application bug).

Colors

Form layouts can range from the simple to the gaudy. If any company standards exist for use of color in labels, prompts, status strings, or any other form or report controls, note them here.

Buttons

I've seen button sizes in applications vary across the map. If a button is sized to include all of its text, it can get quite large.

Note in this topic any standards for buttons, their size, shape, location, and captions. Describe also any layout standards for dialog boxes, for example whether the OK and Cancel buttons are at the bottom or at the right (both are accepted Windows models).

Switchboard Menus

Access 95 introduced a new layout metaphor for switchboard menus, using very small, textless buttons. Other layouts we've seen include list boxes of options, tab controls, and graphics with hotspots (menu examples are provided in Chapter 14, "Navigating in Forms and Applications"). Describe in this topic the standard to be employed for switchboard (button-based) menus in the system.

Bar Menus

Bar menus provide the overall navigation and generic options for the application. Describe in this topic any standards for bar menu taxonomy, placement of options along the bar, and the tradeoffs between application-specific and form-specific menus.

You should also note here any standards for matching bar menu options to toolbar options and command buttons in forms, and the programmatic approach to take when sharing code among these several activation methods.

Shortcut Menus

Shortcut (right mouse button) menus are very useful and powerful options. As such, designers and developers of applications must use some restraint to avoid the tendency to place dozens of options on these menus. Describe in this topic the standard approach to shortcut menus and how the listed features will duplicate or augment features available on the bar menu or toolbar. Describe the situations, if any, in which shortcut menus are disallowed and where the default Access built-in shortcut menus will be allowed or not.

Toolbars

Toolbars are one of the most powerful Windows application features, and with the new CommandBar object technology are easier to fully implement in Access 97. Describe the standards for toolbars in your application, paying special attention to standardized actions and button faces.

Keyboard and Mouse

Every application user has a different balance in their dependence on the keyboard versus the mouse. This fact can come into play in simple areas in application development. For example, I've seen a design team deadlocked over whether to place a graphic on a particular button (catering to mouse-centric users) or text with a keyboard accelerator (for example, Alt+B for Browse for the benefit of keyboard-centric users).

Note here any concerns or standards for keyboard and mouse use relevant to the project.

Status

I find most custom and retail applications, including those from Microsoft, lacking in sufficient visual user feedback. Define here any mechanisms that the application should employ to provide users with status information. Examples of this information are found in Chapter 17, "Bulletproofing Your Application Interface," and include the following:

Terminology

Most companies employ standardized terminology for their commonly used business terms, or they should. Document such terms in this topic.

Within an application, it can be very confusing for users to see the same data item referred to with different terms, for example a Buyer: prompt on one screen and a Customer: prompt on another but both relating to the same data item. The specification process often forces a discussion of terms and how they should be consistently used, which benefits not only the current application but company communication processes in general.

5B. Structural Information

In this subsection, include specific information for each form in the system. The information should be detailed enough to allow the developers to lay out the forms and create the associated program code.

[Name of the First Form]

Each topic header from here to the remainder of the section will be the name of a form in the application-each form is named, then followed by the topics from "Purpose" through "Validation" for that form.

Purpose

Describe in a few sentences the purpose of the form and any unique attributes.

Mockup

Include a sketch, drawing, or actual mockup of the form here, showing as much detail as is required to allow a developer to achieve the user's objectives. Some specification authors prefer to keep all the form mockups together, placing them in an additional subsection (5C) after the structural information or as an "Appendix" item.

Data Source

Note the data source for the form, which may be a table, query, or SQL string (or an English textual representation of it). Describe how the data source may change based on user interaction or other criteria. Note any allowed manual or programmatic filtration or sorting capabilities.

Navigation

Describe how the form is activated and deactivated. Include a discussion of each of the following points:

Controls

Note any special considerations about controls that are not reflected by the mockup diagram, including information about properties and events that should be programmed. For example, selecting a value in a combo box may need to trigger an immediate Requery method of a dependent control in the combo control's AfterUpdate event. If this functionality is not obvious to the developer from the form mockups, it should be noted in this topic.

Events and Procedures

List in this topic any form events that should contain code procedures, and outline the procedure code. Also describe any nonevent procedures that should be included, such as validation code, data processing routines, and the like.

Properties

Describe the properties of the form that will be set to non-default values. A list of form properties is found on the CD-ROM as FORMPROP.DOC.

Validation

Validation features for form records can be a significant portion of both the design team's and development team's effort. As clearly as possible, spell out the data validation requirements here-at the field/control level-and detail how the validation will be achieved (table rule, form rule, program code at record save, program code in a batch, and so on).

[Name of the Second Form]

Repeat the preceding information for each form in the system.

6. Reports

The people who read an application's reports are usually the ones who write the checks to pay for development. Thus, making sure that their needs are properly met is one of the primary objectives of the specification.

In this section, the specification should clearly detail the reporting requirements, creating a plan for developers to follow.

6A. UI Guidelines

In this subsection, note the standards and policies of the company or user group that will dictate the design and programming of the reports.

Report Layouts

Note here any standards for the layout of reports, such as the justification (left, center, or right) of labels, column headers, and controls. Also describe the use of sunken versus flush effects, the look of headers and footers, and so forth.

Fonts and Point Sizes

Note here the user interface standard to be followed by the development team for use of fonts. Describe how the fonts vary for prompts versus data, how group headers and footers will use fonts and sizing, and similar display issues. In general, most users will prefer a larger standard font for reports than for screens.

It may also be wise to specify here the names of all fonts allowed in the application's reports so that developers understand the limited range of fonts to use when creating reports. Otherwise, the look of different reports in a system might vary widely as different developers each apply their own style, or reports may attempt to print using a font not supported by a specific printer.

Colors

Note here if report controls will have any coloration requirements that affect how they are previewed to the screen or how they will print if the target printer makes use of color.

Bar Menus

Navigation within reports that are previewed is usually limited to printing and closing the report. Describe in this topic the exact bar menu options to be used/allowed for the application's reports.

Shortcut Menus

Use this topic to list shortcut menu features, if any, that will be allowed when a report is previewed.

Toolbars

Describe the standards for toolbars to be displayed when reports are previewed, and note how the toolbar options tie to related bar menu options.

Terminology

Document and define the standard company terms in this topic that will be used when creating reports. It is especially important to consider report terminology and to make sure it appeals to the widest possible audience in the following two cases:

6B. Structural Information

In this subsection, include specific information for each report in the system. The information should be detailed enough to allow the developers to lay out the reports and create the associated program code.

[Name of the First Report]

Each topic header from here to the remainder of the section will be the name of a report in the application-each report is named, then followed by the topics from "Purpose" through "Properties" for that report.

Purpose

Describe in a few sentences the purpose of the report and any unique attributes.

Mockup

Include a sketch, drawing, or actual mockup of the report here, showing enough detail so that the developers can create the report. Some specification authors prefer to keep all the report mockups together, placing them in an additional subsection (6C) after the structural information or as an "Appendix" item.

Data Source

Note the data source for the report, which may be a table, query, or SQL string (or an English textual representation of it). Describe any parameters passed to the report and how the user will be allowed to enter or alter the parameters to show selective datasets.

Also describe in this topic the sorting and grouping that will be used to order the data on the report.

Navigation

Describe how the report is activated and deactivated. Note every place in the application where the report will be available and how the user will activate the report at that point and select the data to be printed. Also note the following navigation points:

Controls

Describe nonstandard property settings for report controls and information about the use of report controls that is not obviously inferred from the mockup. Detail the control source expression or reference for totals and other report calculations.

Events and Procedures

List in this topic any report events that should contain code procedures, and outline the procedure code. Also describe any nonevent procedures that should be included, such as calculation routines that must occur before the report is run.

Properties

Describe the properties of the report. It may be useful here to use the property worksheet found on the CD-ROM as REPOPROP.DOC.

[Name of the Second Report]

Repeat the preceding information for each report in the system.

7. Appendixes

Attach to the end of the specification any supporting documents or other relevant information not included in other sections. Some examples follow.

Data Diagrams

If the diagrammatic representations of the database structure were too large to fit neatly into subsection 4A of the spec body, attach them here instead.

Database Schema

Large and unwieldy table structure documentation may be easier to include here rather than subsection 4B of the spec body.

Process Flow Diagrams

Process flow charts are useful to help describe a workflow that has been targeted for automation or to convey the refined workflow of the new system. Place such flow charts here or in subsection 2A in the main portion of the spec.

Form Mockups

In an application with many forms, it may be organizationally easier to include all form mockups together here rather than as topics in subsection 5B of the specification body.

Report Mockups

Attach report mockups here if you prefer to keep them out of the topics in subsection 6B in the main portion of the spec.

Project Timeline

If the project timeline is expressed by a large task list or Gantt chart, include the timeline here rather than trying to cram it into subsection 3E of the spec body.

Test Plan

Include the test plan here if it is too large to place in section 3-D of the spec body.

Design Team Notes

Attach relevant notes, documents, and work papers produced during the design team meetings and research.

History Application

Attach reports, screen shots, training manuals, or other documentation from the existing system(s) to be replaced by this application. Such information was probably used as the starting point for design discussions on this project.

History Data

Document the data structures of legacy (history) data to be imported into the new system.

Integration Information

Document the data structures and flow of other systems that will integrate (share their data or interfaces) with this application.

Future Phases

Include here any documentation and project planning information for future phases of this project.


1996, QUE Corporation, an imprint of Macmillan Publishing USA, a Simon and Schuster Company.