Software Development Project Design Specification Outline

Project Name: User Contact:

Phone: E-mail:

Development Contact: Xpress Systems Web: www.xssoftware.com

Phone: 1-416-663-4341 E-mail: [email protected]

Document Creation: Document Revisions: Last Modified:

Andrei Kossyrine version 3.8 June 12, 2002

Purpose of This Document This document provides a suggested outline for a database application design specification that falls within Microsoft Development Framework guidelines. Hints for creating the content of each section and topic are emphasized and can be deleted from the final document draft. Items to be filled in during the creation of the document are noted with {bracketed text} which should be replaced with the actual text in the final specification document. Different specifications will have different layouts, depending on the responsible personnel and the needs of each project. The flow of this example is only a suggestion to guide the specification process – there is no single "correct" outline for a spec document. Many people working on an 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, the term section is used to refer to a major segment of the document. Within sections are subsections, and each subsection has several topics that describe individual application features.

Contents Purpose of This Document Contents 1. Executive Summary 1A. Overview

Identified Problems Proposed Solution Project Scope

1B. Justification

Cost Justification Return on Investment

1C. Resource Requirements Human Resources Physical Resources Capital Resources

2. Application Processes 2A. Solution Description 2B. Primary Processes 2C. Application Navigation Setup Launching the Application Interface Philosophy Navigation Map

2D. Initial Data Conversion

Source of Initial Data Converting and Validating Initial Data

2E. Links to Other Systems Downloads Uploads Merges and Links

2F. Security Requirements Workgroup Security Application Security

2G. Multi-User Issues

3. Project Mechanics and Management

3A. Project Management Overview 3B. Architecture and Tools Platform/Language Development Tools Reusable Components

3C. Equipment Requirements Client Configuration Server Requirements Connectivity Equipment Upgrades

3D. Application Deployment

User Definition Review Builds Testing Unit Testing System Testing Test Plan Preloading Data Training Deployment Online Documentation User Documentation System Documentation Database Administration Administrators Backup Policies Disaster Recovery Adding Users Localization Ongoing Support Supporting Users Reporting Problems and Enhancement Requests Problem/Enhancement Resolution Guidelines Future Releases

3E. Project Management

Affected Users and Related Parties Project Timelines Responsible Parties Project Administration Issue Management Risk Management Coding and Documentation Standards Future Phases

3F. Financial Mechanics Costing Third Parties Contractual Issues

4. Data Structures and Rules 4A. Data Models and Diagrams 4B. Structure Definition Table Structures Stored Views Table Relationships Business Rules

4C. Data Load

Initial Volumes Future Volumes

5. Screen Forms 5A. UI Guidelines

Form Layouts System Messages Fonts and Point Sizes Colors Buttons Switchboard Menus Bar Menus Shortcut Menus Toolbars Keyboard and Mouse Status Terminology

5B. Structural Information {name of the first form} Purpose Mockup Data Source Navigation Controls Events and Procedures Properties Validation {name of the second form} ...

6. Reports 6A. UI Guidelines

Report Layouts Fonts and Point Sizes Colors Bar Menus Shortcut Menus Toolbars Terminology

6B. Structural Information {name of the first report} Purpose Mockup Data Source Navigation Controls Events and Procedures Properties {name of the second report} ...

7. Appendixes Data Diagrams Database Structure Process Flow Diagrams Form Mockups Report Mockups Project Timeline Test Plan Design Team Notes History Application History Data Integration Information Future Phases

1. Executive Summary An Executive Summary section is a common requirement for business documents and exists to provide the project highlights for managers. 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 Identified Problems 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 This topic provides a brief description of the scope of the project, including some or all of the following points: • When will the project start and end? • What are the major milestones: delivery dates and other deadlines? • What parties will be involved and what are their individual responsibilities? • What existing systems and workflows will be affected during development and deployment?

1B. Justification This subsection is essentially the highlights of project justification, targeted at the readers that will be involved in approving funding for the project.

Cost Justification This topic answers 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: • Increased Profitability • Decreased Expenses • Increased Employee Productivity • Increased Employee Job Satisfaction • Enhanced Competitive Position • Decreased Business Risk

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 the project can be quantified, this topic should include a discussion and possibly a table or graph for clarification. It may not always be easy to tally a solution's positive economic impact on the company because both the benefits of the solution and the costs of the problems it solved must be measurable. 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. Cost Item Current Process Hours Per Month For Task Times: # of Employees Times: Average Hourly Burden Equals: Monthly Cost {$nn,nnn} Equals: Monthly Savings

New Process {nn} {nn} {nnn} {nnn} {$nn} {$nn} {$nn,nnn} {$nn,nnn}

1C. Resource Requirements The introduction to this third subsection of the Executive Summary summarizes 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

This topic details 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: • What the software does, and how it performs these tasks • The coordination of the application objects (tables, queries, forms, and reports) via program code • The processing logic that the application applies to its data

2A. Solution Description This subsection is usually a lengthy, matter-of-fact description of the project and varies greatly by project. It may include additional topics for these and other subjects: • Solution Mechanics • System Architecture • User Interaction • Primary Objects Topics here describe 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: • Bulk import/export of records and the validation of the records before or after receipt • Batch processes, such as mass updates of records at ongoing time points (computing annual pay raises and then updating employee records, for example) • Accounting processes, such as validating and posting transaction batches to a ledger • Data massaging, such as the multi-pass crosstab processing required to produce budget reports that display actual and projected expenses together 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.

2C. Application Navigation This subsection describes how users will interact with the application's interface and includes multiple topics.

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, de-installation, and so forth.

Launching the Application The specification should describe here how users will start the application. For example, the program group, 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. This topic includes information on using a runtime engine or compilation, object security, and application "bulletproofing" techniques to move users between application objects while restricting the availability of the builtin features of the platform. Also discussed 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 This topic displays a navigation map of the application, which is a flow diagram of a user's interaction with the forms and logic processes. A navigation map helps the design team and prospective users review and approve the flow of the application. The diagram shows each form in the application and a visual depiction of how the user moves between the forms. The information can also be presented in text form.

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 This spec includes a matrix showing the tables that will be pre-populated, and the sources of the data for each. Items described: data source by file name, table and field names, or other specifics, plus 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, you may choose 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, a database may be preloaded with information extracted from e-mail messages. This topic of the spec document details the specific conversion algorithms to be used in data preloading and to map source data fields to their new destinations and describes 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, a table in this topic can be used to show the following information:

Historical Table/Field. The location of the historical data, for example "Field PATS.NAME in the DB2 database". New Table/Field(s). The destination in the new system for the historical data, for example "Patient.LastName and Patient.FirstName". Conversion Logic. The conversion process to apply during the preloading, for example "Change the case of PATS.NAME from uppercase to uppercase/lowercase, then take the first element in PATS.NAME and place it in Patient.LastName and the second element into Patient.FirstName." Rule. The criteria for record/field selection during the conversion, for example "Ignore patient names that are Null during conversion and print an exception list showing single-name patients but do not convert them." Historical Table/Field New Table/Field(s) Conversion Logic {"from" location} {"to" location} {conversion logic process} selection rule}

Rule {record

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. This subsection of the specification document details such requirements for the application.

Downloads This topic describes the type of data that will be pulled into the application from other systems . For example, an inventory control system may pull the current product pricing from the corporate AS/400 minicomputer each month before running inventory processing routines. This topic also points out the frequency of data downloads, the work that must be done in the host system to facilitate the extraction, the linkage mechanisms to the external data, and detail the import and validation logic to be used.

Uploads It is almost as common for an applications to send data to other systems as to receive data from an external source. For example, a medical clinic billing system may 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. This topic details any similar requirements of your application to send data to other computer systems, as well as the frequency of the exports, the validation to perform on the data before sending, the communication mechanism. Also, this section of the spec document defines the 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 field in the data.

Merges and Links

In most PC database systems, 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 example, users frequently request reporting routines to send data summaries to spreadsheet programs for analysis. If an application will help users merge data to a word processor, a spreadsheet, a presentation, the Web, or any other destination, the requirements for such features should be mentioned in this topic of the spec.

2F. Security Requirements If the application will be secured, this subsection should detail the security requirements and their enforcement mechanisms in the structure and user interface.

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

Application Security In this topic, the groups detailed in the previous Workgroup Security topic are mapped 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 workgroups, the structure and code for such security is also described.

2G. Multi-User Issues The multi-user nature of the application is determined by the number of concurrent users expected and their anticipated data entry/edit behavior. This section details these expectations in this subsection of the spec document, and lays out the resolution mechanism for any problems that will accrue from the expected usage patterns. Specifically, this subsection should describe multi-user loads and the expectation for related collisions. Define 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 when applying 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 project management section, this subsection points out 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/Language The primary platform for an application is its operating system and development languages, which should be noted in this part of the specification. An application may actually involve multiple development languages, each one specializing in a different task: data access, user forms, reports, interface extensions, business objects, reusable components, interoperability/automation, program code, etc. List each of these language tools to be used in creation of the solution.

Development Tools This topic describes any third-party tools or extensions that will be employed in addition to the primary platform: development tools, add-ins/wizards, ActiveX controls, Software Development Kit (SDK) products, code collections, and similar extensions.

Reusable Components This topic details any components which already exist within the organization and can be reused or adapted for the application. Reusable components include interface objects, business objects, class objects, Automation servers, compiled Dynamic Link Libraries and executables, code procedures, and code libraries.

3C. Equipment Requirements In this subsection, the spec document details 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, the actual configuration requirements, preferred vendor, and any installation issues should be detailed here. If the application's data will reside on a shared server, the server name, the path for the data back end, security configurations, and any issues involved in sharing the server with other applications or databases should be specified as well.

Connectivity This topic describes any special connectivity requirements for users of the application. Connectivity issues arise in one of the following areas: User Logins. Descriptions of how users of the application gain login rights to the network domain on which the data resides. Drivers. Details of any requirements here for the users to install connectivity drivers in order to access the data. If the drivers will be installed by the application setup or by the user, this should be specified as well. Remote Users. Users who will access the data over telephone lines or a wide-area network may have special modem, software, login account, or other configuration needs, which should be listed in this topic. Laptop Users. If the application allows for any form of data replication or checkout/checkin, the policies and procedures for mobile users should be clearly spelled out in the spec.

Equipment Upgrades This specification topic should name the user workstations that must be upgraded to comply with the configuration and connectivity requirements previously mentioned in this section. 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.

3D. 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 This topic describes 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. This topic details how many application reviews are in the development cycle, what will be provided in each review build, and when they occur, the users that will participate in each review and how the review process will work. This information could be presented in a table like the one following. Build Features Included Distribute To User Interface Review Working Model Beta 1

Testing A good spec document should detail the plans for thoroughly testing the application. 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. This topic describes the involvement of the development team in the testing process and the scheduling and verification of such efforts.

System Testing Final testing of the integrated system is usually done through several releases in a cycle called system testing because the entire system is tested as if the application is complete. Described here are 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. 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.

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.

Preloading Data In the Initial Data Conversion section earlier, 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. This topic clarifies and resolves any such issues, and details the resolution of such issues.

Training This topic describes the user training plan for the application. At the least, the following points should be explained: • Who will be trained. • Who will do the training. • A training timetable. • What training materials will be created and by whom. • What training facilities and equipment will be utilized and when.

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: • The release timetable for the initial deployment, and how the training and equipment upgrade schedules precede or overlap deployment. • The order of deployment by user, workstation, or workgroup. • The expected impact on user productivity during deployment. • The parties responsible for managing deployment and the hands-on installation. • Potential deployment problems and the strategy for addressing each.

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 The specification should detail here the requirements for producing hard copy documentation. If possible, an outline, target page count, and other parameters for the user documentation should be provided. Sometimes the spec can reference an existing document from a previous project to use as a model, rather than providing detailed writer's guidelines here, or the sample document could be included as an appendix item. More and more developers have adopted the model of turning the hard copy documentation into online documentation. If the organization utilizes this strategy, it will take special efforts to organize and write user documentation so that it can easily be converted to a compiled Help file or online Web pages. Such documentation strategies or reference a company style guide document should be detailed here 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 or large size is delivered with documentation on such elements as the following: • Database Structure and Relationships • Ongoing Maintenance of the System • Principal Processing Logic • Primary Development and Coding Techniques Employed • Strategies for Extensibility In this topic, such system documentation elements are usually included. 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 The preceding System Documentation topic noted that this document should detail the important procedures for system maintenance. The informa tion 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.

Administrators This topic describes who will administer the database and what the scope of each person's responsibilities and authority will be.

Backup Policies This topic discusses the backup policies for the database back end, including backup time s, responsible parties, and off-site storage plans as well as resolution steps for "bumping" users from the application so that repairs, compacts, tune-ups, and backups can get exclusive locks on the data file(s).

Disaster Recovery

What are the disaster recovery policies for the application? This topic details the recovery steps for the "worst case scenario," usually the destruction of the data server or the building in which it resides.

Adding Users This topic describes 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, those strategies have to be documented 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. This is done in the following three subtopics.

Supporting Users This topic describes how users will be supported when they have questions, support mechanisms, including support by telephone, e-mail, voice mail, fax, pager, intranet, knowledge base, or in person. Also designated support personnel and defined targeted response/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 (this is called "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 such spillover and how these will be addressed.

Project Timelines This topic defines the "final delivery", including the specific components of the delivery: Timelines. The process steps of the project, and the order in which they will be executed, including a spreadsheet, Gantt chart, or other visual depiction of the project timeline here or in the Appendixes section, if possible. Milestones and Acceptance. The major milestones of the project, exactly what will be delivered at each milestone, and what review and acceptance processes will be used to assure that the delivery complies with expectations.

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. An effective project team includes people with a variety of responsibilities. Role Person(s) Program Manager {name the hands-off manager responsible for fitting the project into the company's mission} Project Manager {name the hands-on manager responsible for oversight and delivery} Development Manager {name the manager of the development team} Developers {name the coders and testers} Ultimate Users {name the highest-level beneficiaries of the project} User Representatives {list the user community representatives participating in design and development oversight} Users {list the users of the released product} IT Liaison {name the Information Technology group member who fits the project to IT's business model} Support Personnel {list the ongoing maintenance and support staff}

Project Administration This topic describes more clearly the guidelines and techniques that will be employed by the project manager to ensure a timely and successful completion, including 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 This topic discusses 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. Too many project development efforts rely on cryptic voice messages and hand-scrawled notes when better communication and time management technologies exists.

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, future versions 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: • What is the objective of each future phase? • When does the phase start and end? • Who will manage the phase? • Who will design the phase? • Who will develop the phase?

3F. Financial Mechanics This subsection provides the details to support the financial (costing) information provided earlier in the Executive Summary section.

Costing This topic provides detailed cost breakdowns here, listed by phases, months, milestones, or other logical arrangement, including the cost of equipment upgrades, components and tools, training, and other non-development capital outlays.

Third Parties This spec topic names the parties outside of the company that will be 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 (as defined in the preceding Third Parties section), text describing the contractual or other legal relationship with each vendor may be presented here, including the contracting parties, the major contract elements (which should cover topics such as nonperformance, poor performance, and code ownership), mechanisms for enforcement and 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 the most time has to be expended when creating the 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 This subsection includes any visual representations of the database 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, they have to be included in the Appendixes section and their location as to be referenced here.

4B. Structure Definition This subsection provides a place to document each facet of the database structure.

Table Structures This topic includes a listing of the table fields, indexes, and all related properties for each data table. The layout and depth of this information varies across different developers and projects. Spreadsheet documents may be more appropriate to list tables and fields and to capture the primary properties of both. This allows the design team a single, common platform from which to actively discuss and clarify the fine points of the data structure. Alternately, databases designs can be recorded and diagrammed using various retail development tools. 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, the tables have to be attached here, or in the Appendixes section and referenced.

Stored Views Saved views or queries are used to provide concurrent access to data in multiple related tables. This topic documents these saved objects: • "Data aggregation" queries joining sibling records or tables in parent-child relationships, for quick access and reuse. • "Record source" queries providing selective datasets used to drive forms and reports. • "Action" queries to move, update, delete, and otherwise alter data records.

Table Relationships

This topic describes the relationships between the tables, how they will be created, and how data integrity between related records will be enforced. The relationship information should match the visual depiction of the database structure in Data Models and Diagrams previously.

Business Rules The database engine may provide some built-in mechanisms for data validation. Additionally, most applications include some programmatic data validation. 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. Validation may be performed during entry, edit, deletion, archival, and batch/bulk processing.

4C. Data Load When building a database application, it is helpful to document for the development team in this subsection the quantities of users and data that the application and data structure must ultimately support. Such informa tion assists the developers in performance tuning the application, load balancing, and addressing multi-user issues.

Initial Volumes This topic lists facts about the initial load on the application, including the expected number of concurrent users, data transactions, and record loads for each table, as well as quantity and quality of data to be preloaded from existing systems.

Future Volumes This topic should provide tables or graphs showing how the user and data loads on the application will change over time, beginning with the load information in the preceding topic Initial Volumes and projecting it forward to various time milestones in 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, the following objects are usually described explicitly in this topic to avoid expensive reworks later in the project: entry, edit, dialog, menu, and other forms. The navigation map diagram for moving between application forms, described in the Application Processes section earlier, fits just as well in this topic.

5A. User Interface Guidelines This subsection describes the standards and policies of the company or user group that will dictate the "look and feel" of the application's forms. Standards are developed by taking into account the following considerations regarding the application's expected users: • What are their skills and habits? • What applications do they use now? • What do they like and dislike about their current software toolset? • What job are they ultimately trying to do with this application? • What shortcuts do they need when in a hurry? • How do they locate information? • How do they enter and edit information? • How do they verify and audit information? • Do they multi-task or single-task? • Do users job share? Equipment share? • What are their abort patterns? When and why do they have to cancel or rollback processes? • How do they deal with interruptions, keep their place when they leave their desk, and recover from disasters?

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

System Messages This topic describes any special considerations about how messages (alerts) should be displayed for users. For example, some applications make use of error messages built in to the platform/language, 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 This subsection discusses 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: Fonts and Point Sizes for Buttons. If the application's standard will differ from the Windows standard, that fact here should be noted. Fonts and Point Sizes for Data and Prompts. Depending on the application, the users, the resolution of the average workstation, and other factors, the default font and size for labels, text boxes, combo boxes, and similar controls may differ from the defaults provided by the platform or development tools. 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.

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, they have to be noted here.

Buttons Button sizes in applications vary across the map. If a button is sized to include all of its text, it can get quite large. This topic notes any standards for buttons, their size, shape, location, and captions, as well as 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), or are located somewhere else.

Switchboard Menus A switchboard menu is a form that helps users navigate. It may utilize buttons, list boxes, tab controls, and graphics with hotspots. This topic describes the standard to be employed for switchboard menus in the system.

Bar Menus Bar menus provide the overall navigation and generic options for the application. This topic describes any standards for bar menu taxonomy, placement of options along the bar or pulldowns, and the tradeoffs between application-specific and form-specific menus. 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 should also be noted in this subsection.

Shortcut Menus Shortcut (right mouse button or "context") 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. This topic describes the standard approach to shortcut menus and how the listed features will duplicate or augment features available on the bar menu or toolbars.

Toolbars Toolbars are one of the most powerful Windows application features. This topic notes the standards for toolbars in your application, paying special attention to standardized actions, locations, tool tips, 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, such as the debate whether to place graphics on buttons or text with keyboard accelerators. This topic covers any concerns or standards for keyboard and mouse use relevant to the project.

Status Most custom (and retail) applications lack sufficient visual user feedback. This subsection defines any mechanisms that the application should employ to provide users with status information. Examples include the following: Mouse Cursor. Programming the mouse to become an hourglass in all areas where the user is waiting on the system produces a big improvement in the usability of an application. Status Bar. How the status bar area will be employed to tell users what is currently taking place or what action is expected. Message Boxes. Most data processes that affect records should show an alert before running to ask the user to confirm the operation. In some applications, an alert is shown at the end of the process so that the user knows the process ran to completion. This is especially true of bulk operations like mass deletes or exports. Issues like these are detailed in this topic.

Terminology Most companies employ standardized terminology for their commonly used business terms, or they should. Such terms should be docume nted 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 This subsection includes specific information for each form in the system. The information should be detailed enough to allow the developers to build the forms and create the associated program code.

{name of the first form} Each topic header from here to the remainder of the Structural Information 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 The purpose of the form and any unique attributes.

Mockup Includes a sketch, drawing, or screen capture of an 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 Notes the data source for the form, which may be a table, query, or SQL string (or an English textual representation of it). Describes how the data source may change based on user interaction or other criteria. Notes any allowed manual or programmatic filtration or sorting capabilities.

Navigation Describes how the form is activated and deactivated. Includes a discussion of each of the following points: Entering. Describes how this form is activated and any specific logic that will occur on the form's initiation (open, load, activate, etc.) events. Exiting. Notes how the user leaves the form, whether by closing or branching to another form. Bar Menus. Describes the contents of the menu to be used with the form and the logic attached to each nonstandard option on the menu. Shortcut Menus. Lists the options included on the shortcut menu for the form and the logic attached to any nonstandard options on the menu. Toolbars. Notes the buttons that will be on this form's toolbar and the action or code routine that each tool will call.

Controls Notes any special properties or other considerations about controls that are not reflected by the mockup diagrams, including information about property changes and events that should be programmed. For example, selecting a value in a combo box may require code to trigger an immediate requery of a dependent control.

Events and Procedures This topic lists any form events that should contain code procedures, and outline the procedure code. Also describes any nonevent procedures that should be included, such as validation code, data processing routines, and the like.

Properties Describes the properties of the form that will be set to non-default values.

Validation Validation features for form records can be a significant portion of both the design team's and development team's effort. This topic should spell out the data validation requirements and enforcement mechanisms as clearly as possible for information that is entered or edited via the form, as well as validation at the field/control level, and how the validation event 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} Another topic whose title is the name of the next form. Repeats for the form the previous subtopics from Purpose through Validation and fill in the appropriate information. Then the same for the third form, and so on until all forms are documented. {Repeat here 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 spec should clearly detail the reporting requirements, creating a plan for developers to follow.

6A. User Interface Guidelines This subsection notes the standards and policies of the company or user group that will dictate the design and programming of the reports.

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

Fonts and Point Sizes Notes here the user interface standard to be followed by the development team for use of fonts. Describes how the fonts vary for prompts versus data values, how page and 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 Notes 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. This topic describes the exact bar menu options to be used/allowed for the application's reports in preview mode, any specific menu taxonomy, the placement of menu options, and menu coding requirements.

Shortcut Menus This topic lists shortcut menu features, menu taxonomy, placement of options, and coding requirements if shortcut menus will be allowed when a report is previewed.

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

Terminology This topic documents and defines the standard company terms 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: The audience extends beyond users of the application. Personnel reading reports who are not familiar with the system will not understand terms defined only within the context of the system. Reports should use generic terms or include the definition of specific terms in the report footer or endnotes, if necessary. The audience includes managers. When managers will be using specific reports for corporate decision making, it is important to use terms that fit their vocabulary and job role. For example, a report that shows the total value of inventory items per product could legitimately label the total "InvQty," which is the table field name and a shorthand for "Inventory Quantity." However, management-level users of the report may get more value from the data item if it were labeled "Inventory On Hand" or other term that ties to their common vocabulary.

6B. Structural Information This subsection includes 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 Structural Information 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 Describes the purpose of the report and any unique attributes.

Mockup Includes a sketch, drawing, or screen capture of an actual mockup of the report 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 report mockups together, placing them in an additional subsection (6C) after the structural information or as an appendix item.

Data Source Notes the data source for the report, which may be a table, query, or SQL string (or an English textual representation of it). Describes any parameters passed to the report and how the user will be allowed to enter or alter the parameters to show selective datasets. This topic also describes the sorting and grouping that will be used to order the data on the report.

Navigation

Describes how the report is activated and deactivated. Notes 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 notes the following navigation points: Bar Menus. Describes the contents of the menu to be used with the report and the logic attached to each nonstandard option on the menu. Shortcut Menus. Lists the options included on the shortcut menu for the report, if any, and the logic attached to any nonstandard options on the menu. Toolbars. Notes the toolbar buttons that will be on this report's toolbar and the action or code routine that each tool will call.

Controls Describes nonstandard property settings for report controls and information about the use of report controls that is not obviously inferred from the mockups. Details the logic for computed control values, totals, and other report calculations.

Events and Procedures Lists in this topic any report events that should contain code procedures, and outline the procedure code. Also describes any nonevent procedures that should be included, such as calculation or layout routines that must occur before the report is run.

Properties Describes the properties of the report that will be set to non-default values.

{name of the second report} Another topic whose title is the name of the next report. Repeats for the report the previous subtopics from Purpose through Properties and fills in the appropriate information. Then the same for the third report, and so on until all reports are documented.

7. Appendixes This section contains supporting documents that are not part of the specification document file or are quite large and are less obtrusive to the flow of this document when placed at the end.

Data Diagrams If the diagrammatic representations of the database structure were too large to fit neatly into the subsection Data Models and Diagrams of the spec body, they should be attached here instead.

Database Structure Large and unwieldy table structure documentation may be easier to include here rather than the Structure Definition subsection 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. Such flow charts should be placed here or in the subsection Solution Description in the main portion of the spec.

Form Mockups In an applic ation with many forms, it may be organizationally easier to include all form mockups together here rather than as topics in the Structural Information subsection of the form definition area of the specification body.

Report Mockups Report mockups should be attached here if they are not included in the Structural Information subsection of the report definition area of the specification body.

Project Timeline If the project timeline is expressed by a large task list or Gantt chart, the timeline should be included here rather than in the Project Timelines area of the spec body.

Test Plan Includes the test plan if it is too large to place in the Test Plan section of the spec body.

Design Team Notes Contains relevant notes, documents, and work papers produced during the design team meetings and research.

History Application

Contains 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 Documents the data structures of legacy (history) data to be imported/preloaded into the new system.

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

Future Phases Includes any documentation and project planning information for future phases of this project that expands on the Future Releases topic earlier in the spec.