Write the Technical Specification

After the façade is presented, the functional specification is changed (if required), and if the owner is satisfied with the façade, the design may be completed. The edge case XML produced in the façade effort defines the data model for the solution. The XML elements within the edge case XML specifications represent object instances serialized into XML. However, no code may exist to produce the objects that are serialized into XML. The remaining effort of the design step is to describe how to configure existing solutions or build a new solution that provides objects that may be instantiated to represent the objects identified in the façade effort so that they may be serialized into XML.

The technical specification should be detailed enough so that a programmer or team can produce the desired solution as specified. Documenting the design also tests the validity of the design by forcing the developer to reduce his or her thoughts to paper. In addition, the technical specification serves to enhance the functional specification as an as-built plan of the software. Much like the functional specification, the technical specification should provide the following elements:

• Identification of every technical requirement so that development can reference parts of the specification in correspondence

• Change control record

• Table of contents

• Cover page with owner name and project name

• Footer with your company name, confidential info, and print date

• Reference of the functional specification name, title, and version that were used to produce the technical specification

The same hierarchical numbering strategy that was used in the functional specification should be used in the technical specification. (Refer to Figure 18-4.) The front page of the technical specification should be produced in much the same way as the cover page for the functional specification.

Technical Specification Template

A technical specification template or common outline should be created, considering the dangers of consistency for the sake of consistency. The template is the default setting, and you should stray from it as required to make the document meet the needs of describing the design. If you find that the document template must be changed in the same way for each project, alter the document template. A good outline for the technical specification follows:

Introduction

• Summary of the Solution

• List of items that need to be built (such as scripts, components, database scripts)

• List of items or files that might be changed or edited in an existing solution

• Definitions and acronyms

• Definition of any potentially confusing terms that are used in this document or the technical environment

• Definition of acronyms used throughout the document or in the owner's industry

• Out of scope

• List of things that a developer might think they should do but that should not be done

• Assumptions

This section should set the stage regarding the circumstances surrounding the production of the specified solution. The introduction should not restate parts of the functional specification; rather, it should describe the project as though the developer were familiar with the functional specification. The danger in restating information from the functional specification is that this document is generally updated or owned by someone other than the technical specification author. The functional specification might be updated to prepare for some future enhancement to the solution. If the technical specification has information in the introduction section that was changed in the functional specification as a result of an update, the technical specification would contain incorrect information.

Object Model

• Results from façade

This section represents the actual instances that were discovered in the façade exercise. This section should offer a summary diagram for how these objects relate to one another in the real world. The purpose of this section is to document the analyses that resulted from the façade exercise and also offer the supporting basis for the class model that is created for this solution.

Class Diagram

• Description of each class's purpose

• Relationship to other classes (Inheritance, Composition, and Aggregation)

• Functions in the object (Purpose, Description of interface, Parameters, Data types)

• Initialization state settings that apply to the solution and related objects

• Pseudo-code of the functions

This section contains the code that will support the object instances described in the object model. These two sections may seem similar, but the difference is that certain classes may represent more than one object-instance. The class model offers an abstraction from real-world entities to the actual code structures that represent real-world entities.

Data Diagram

• Description of container or tables

• Description of all fields or attributes in a table or container

• Description of keys among tables

This section simply describes the data layer or how the data is stored in the system. One could think of the class diagram as the in-memory storage and the data diagram as the hardware-based storage system. This section will likely describe a database design, but it could describe files or directory items.

Unit Testing

• Description of test harness for solution

• Edge case data that should be used in unit test to validate code

This section describes what the solution must demonstrate the ability to perform if it was produced properly. It might include a test or set of tests that must be coded to test the solution and describe whether the solution ran correctly. This section should also describe the data that provides an edge case scenario for unit testing the solution. Edge case data might include dealing with strings that contain all of the special characters, such as ~`!@#$%^&*()_+-{}[]\|;:'"<<>>?/.,.

Other edge case data might include a data set of bogus data that is meant to test the execution time on the largest data set that the solution was meant to encounter.

Deployment

• Deployment diagram

• Description of perquisites required in host (Libraries, Versions)

• Script for deployment (Steps that need to be performed, Order of execution, Host configuration)

• Validation that the deployment was successfully executed

• Uninstallation steps

This section describes how the solution must be rolled or moved into a production environment. The deployment diagram demonstrates the files with which classes and functions will be hosted. For example, because a solution is likely to consist of one or more DLLs, the diagram should identify existing DLLs or new DLLs that will host the classes or functions. The solution's dependencies should also be identified by version and name. Install and uninstall instructions should also be provided, along with steps for verifying that the installation worked properly.

Functional Test Scripts

Because the functional test scripts are based on the content of the functional specification, they are included as a deliverable in the design step. The test scripts document the actions that the solution must perform flawlessly to demonstrate that the solution meets the needs of the functional specification.

The functional test scripts should be documented so that an individual responsible for the development or business requirements can execute the test script. Much like the other documents associated with the solution development process, the script should include the following elements:

• Change control record

• Cover page with owner name and project name

• Footer with your company name, confidential info, and print date

The format of the test script should be a table that includes the following fields:

• Sequence Number Number to uniquely identify the step in the script

• Action Item Title or name of the step; a good name to use is where the action begins or the section in which the action takes place

• User Action A description of the action the tester should perform on the solution

• Inputs A description of what the tester does to make the solution respond

• Expected Results What the solution should produce

• Actual Results What the solution actually produced

• Pass or Fail Boolean value indicating whether or not the test passed