U.S. Department of Transportation
Federal Highway Administration
1200 New Jersey Avenue, SE
Washington, DC 20590
202-366-4000


Skip to content U.S. Department of Transportation/Federal Highway AdministrationU.S. Department of Transportation/Federal Highway Administration

California Division

Home / About / Field Offices / California Division / Systems Engineering Guidebook for ITS

Home What's New Systems Engineering Guidebook Views Search Glossary Resources Feedback Site Map

8.4.7 Design Specification Template

Purpose of these Documents

These documents describe how the system is to be built. They take the requirements [what the system will do] and translate them into a hardware and software design that can be built. Collectively, the purpose of these documents is to:

  • Provide a documented description of the design of the system that can be reviewed and approved by the stakeholders
  • Provide a description of the system in enough detail that its component parts can be procured and built
  • Provide a description of the hardware and software system components in sufficient detail for them to be maintained and upgraded
  • For most projects, two levels of design specification are developed. The High Level Design Specification Document supports the project architecture, interfaces, and sub-system requirements. The Detailed Design Specification Documents provide the build-to specification for software and hardware construction

For some systems, it is advisable to create separate documents, called Interface Design Documents, to describe the internal and external interfaces of the system being built.

Tailoring these Documents to Your Project

Any ITS projects that are structured to produce a physical hardware / software system require some level of design description of the system to be procured or built. Study projects with only paper products don’t need them. For simple systems or for systems that are completely COTS, only one minimal document is sufficient [perhaps just a list of the items to be procured].

If a project involves the fabrication of hardware components, the information contained in the design specifications are supplemented with drawings from which the parts are built. Construction and installation drawings may also be required.

If a project involves the development of custom software, even relatively simple software, then both documents are strongly recommended.

A software design is documented by these specifications and by the source code itself. It is vital that the Detailed Design Specification exists along with the source code. Further, the specification must track to this code.

Interfaces that are not shared with others may be completely contained in the Detailed Design Specifications otherwise they are specified in the Interface Specification. Some modern programming techniques make processor-to-processor interfaces completely transparent to the code. However, some interface methods, especially interfaces to existing external systems, are very specialized and unique. In these cases, a separate document that can be easily reviewed by engineers on both sides of the interface is very useful.

Checklist: Critical Information

check Does the High Level Design Document include definition of requirements unique to the chosen architecture [interfaces between sub-systems, for instance]?
check Is the definition of each requirement from the Requirements Document complete enough for implementation? Or, does it need to be expanded in the High Level Design Document?
check Are system requirements traced to the sub-systems in the High Level Design Document?
check Are commercial off-the-shelf products identified in the High Level or Detailed Design Document?
check Is the design approach for common software methods defined, as appropriate, in both the High Level and Detailed Design Documents?
check Is the architecture, both hardware and software, of the sub-systems [components and interconnections] defined in the high level design specification?
check Are any necessary database schema and structures defined in the High Level and Detailed Design Documents?
check Are the hardware components defined in enough detail in the design documents to support procurement or fabrication?
check Has the trace from requirements to hardware and software components been checked and verified?
check Is the Detailed Design Document linked to the source code components, that is, do they use the same object names, file names, attribute names, and method names?

HIGH LEVEL DESIGN SPECIFICATION TEMPLATE

IEEE Std 1233 Guide for developing System Requirements

IEEE 1471-2000 Recommended Practice for Architectural Description of Software Intensive Systems

section

contents

Title Page

The title page should follow the Transportation Agency procedures or style guide. At a minimum, it should contain the following information:

  • HIGH LEVEL DESIGN SPECIFICATION FOR THE [insert name of project] AND [insert name of transportation agency]
  • Contract number
  • Date that the document was formally approved
  • The organization responsible for preparing the document
  • Internal document control number, if available
  • Revision version and date issued

1.0 Purpose of Document

This section is a brief statement of the purpose of this document. It is a high level description of the architecture [hardware and software] of the system. It summarizes the contents of the document. Sometimes the High Level Design specification is used to document some requirements not covered elsewhere, such as an operator interface or interfaces to external systems. It also may be necessary to include functional requirements arising from the internal interfaces created between the sub-systems.

2.0 Scope of Project

This section gives a brief description of the planned project and the purpose of the system to be built. This section can be copied from a previous document, and is included for completeness. This may be the only document which some project participants and stakeholders may see.

3.0 Sub-systems

This section describes the architecture of the system and how it is divided into sub-systems, when that is found to be necessary. Simpler systems may not need to be subdivided, and if so, this section is void.

When sub-systems are needed, each is described in terms of its purpose, its functionality, its interfaces with other sub-systems, and its component parts [hardware and software]. If the requirements call for different capabilities at multiple sites, then the allocation of the sub-systems to these sites is shown.

In order to describe the functionality of a sub-system, it is necessary to allocate system requirements to each sub-system. All requirements must be covered by at least one sub-system. However, some requirements [and especially performance requirements] may be applicable to several sub-systems. An explicit trace of all requirements from the Requirements Document into the sub-systems is a part of this document.

In addition to the system requirements, additional requirements may be necessary to show how the sub-systems work together. Those types of requirements are analyzed and documented here.

4.0 Hardware Components

This section identifies the hardware components of each sub-system. It identifies them by name, function, capabilities, source [manufacturer], and quantity. It shows the interconnections between the components [e.g. point-to-point, or local area network]. If a hardware component needs optional components or features, they are listed and defined at this time.

This section also includes a trace of requirements, where applicable, into the hardware components.

5.0 Software Components

This section describes the preliminary design of the software application. It shows the allocation of the software to sub-systems and to hardware elements. It shows and identifies the COTS software packages to be used; and their allocation to sub-systems and to hardware components. It also shows/identifies all custom designed software packages and their allocation to sub-systems and hardware components. It shows the architectural relationship between the various software packages, both custom and COTS.

The high level design of each custom software package is described. The method used for this description depends on the methodology being used for software design. That methodology may be object-oriented design, data flow design, structured design, or any other method chosen by the project and the software development team.

For example, if an object oriented software design methodology is to be used, the description of the custom software components for the High Level Design specification would include:

Preliminary class description for significant internal and external classes necessary to implement the functional requirements

  • Preliminary description of the attributes, methods, and relationships of each class of objects
  • Class diagrams and other diagramming methods as appropriate, such as, sequence, package, activity concurrency, and state diagrams
  • Component diagrams to describe the physical partitioning of the software into code components
  • Descriptions of common patterns to be used in the software design, such as, the pattern to be used for inter-process communication, or for implementation of an operator interface
  • Trace requirements into each software package

6.0 Sub-system Requirements

This document may be used to describe additional requirements that were not covered in the requirements specifications. These may include, but are not limited to:

  • Showing greater detail of previously defined functional requirements based on additional functional analysis; for instance, defining the details of a complex algorithm
  • Providing complete details of complex requirements, such as a detailed description of a complex operator interface where considerable work with operations personnel is necessary before a definitive statement of the requirement can be made
  • Providing complete details of an interface with an external system
  • Stating requirements which result from the separation of the system into sub-systems. That is, identifying functional requirements for the way these sub-systems work together

Of course, these types of requirements [with the exception of the last type] also may be included in the Requirements Document or documented in separate documents, as deemed appropriate.

7.0 Applicable Documents

This section lists the applicable documents that constrain the design process. Such documents may include standards and external system specifications.

DETAILED DESIGN SPECIFICATION TEMPLATE

section

contents

Title Page

The title page should follow the Transportation Agency procedures or style guide. At a minimum, it should contain the following information:

  • DETAILED DESIGN SPECIFICATION FOR THE [insert name of project] AND [insert name of transportation agency]
  • Contract number
  • Date that the document was formally approved
  • The organization responsible for preparing the document
  • Internal document control number, if available
  • Revision version and date issued

1.0 Purpose of Document

This section is a brief statement of the purpose of this document. The purpose is, to expand and complete the preliminary design descriptions included in the High Level Design Document.

2.0 Scope of Project

This section describes the project and may be lifted from the High Level Design Document.

3.0 Sub-systems

This section completes the description of the system architecture and the sub-systems, as necessary.

4.0 Hardware Components

This section completes the description of the hardware components. It contains a detailed list of the exact hardware items to be procured by name, part number, manufacturer, and quantity. If necessary, it lists any hardware component specifications or drawings which have been prepared by the design team.

5.0 Software Components

This section completes the description of the software components. It contains a detailed list of the COTS software products to be procured, by vendor, name, part number, and options.

If the project involves custom software applications, this section becomes the dominant and largest part of the Detailed Design Document. Its purpose is to provide enough information so the code can be developed. Subsequently, so the code can be understood for maintenance and system upgrades. As a result, the overriding requirement is that the descriptions of the software components are complete and the link between these descriptions and the actual source code is clear and explicit.

The Detailed Design Specification is primarily a completion of the preliminary information in the High Level Design Specification. Any corrections to the information in the previous document should be made at this time. Again, if a software design tool is used, it may produce most of the Detailed Design Specification.

For example, if an object oriented software design methodology is to be used, the description of the custom software components for the Detailed Design Specification would include expansion of the following from the High Level Design Specification:

  • Class description for significant internal and external classes necessary to implement the functional requirements
  • Description of each class attributes, methods, and relationships
  • Class diagrams and other diagramming methods as appropriate, such as: sequence, package, activity concurrency, and state diagrams
  • Component diagrams to describe the physical partitioning of the software into code components
  • Descriptions of common patterns to be used in the software design, such as, the pattern to be used for inter-process communication, or for implementation of an operator interface

INTERFACE DESIGN DOCUMENT TEMPLATE

section

contents

Title Page

The title page should follow the Transportation Agency procedures or style guide. At a minimum, it should contain the following information:

  • INTERFACE DESIGN DOCUMENT FOR THE [insert name of interface] FOR THE [insert name of transportation agency]
  • Contract number
  • Date that the document was formally approved
  • The organization responsible for preparing the document
  • Internal document control number, if available
  • Revision version and date issued

1.0 Purpose of Document

This section is a brief statement of the purpose of this document. It defines the function and design of an interface between two parts of the system or between the system and an external system.

2.0 Scope of Project

This section describes the project and may be lifted from the High Level Design Document.

3.0 Interface Purpose and General Description

This section is used to describe, in operational terms, the purpose of this interface. It shows how that purpose relates to the overall operation of the system being designed. It describes the information flow, in both directions if that is applicable, and the actions or conditions that cause information to be transferred across the interface. It describes where that information comes from and where it is used.

4.0 Communications Method

This section describes the communications protocols associated with information flow across the interface. Especially, protocols that the programmer has to use in order to make the transfer occur. This form and content of this section, and the next, are very dependent on the type of communication method used. For instance, the description of a database replication method is different from a File Transfer Protocol [FTP] method or from a remote procedure call method. There are many other communications methods that can be used. For internal interfaces, selection of a process-to-process communications method is part of the software design effort. However, when communicating with an external system, the usual case is that system already exists, and has a defined communication protocol. In this case, the software designer must build a compatible interface. That work is facilitated by this document.

5.0 Specific Interface Design

Along with the previous section, the form and content of this is completely dependent on the method used to transfer information, or data, from process to process and from system to system. This section focuses on the form and content of the data elements themselves instead of the communications protocols described before.

For instance, if database replication is used, this section describes the logical data structure and the specific database information contained in the fields of the database. If a message method is used, this section describes the content of each field of the message and its allowable values. If a remote procedure call type of interface is implemented, this sections describes the function of the call, the parameters passed with it, the parameters returned by the call, and the actions taken by the remote procedure.

These are just three examples of a variety of methods that may be used. This section must contain enough information to allow the software developer to design and write code to implement the interface.

 

Related Task Examples Checklist  

 

Return to top
Federal Highway Administration | 1200 New Jersey Avenue, SE | Washington, DC 20590 | 202-366-4000