Best Practice - Design Documentation

Best Practice

Title page

1.0 Introduction

2.0 Design

3.0 Glossary

4.0 Change Log

Template Design Document

Example Design Document


Rationale

The Design Document tells the implementers the following about the software:

The combination of the Requirements Documents, Specification Documents and Design Document gives the implementer all of the information required to write the software.

The information in the Design Document complements the information in the source code documentation. There must be NO duplication of information between the Design Document and the source code documentation. A change in documentation of source code should not require a change to the Design Document.

TBS

Best Practice

The remainder of this document contains the Best Practices for writing a Design Document.

Follow this link to find Best Practices that are common to all project documents.

Title Page

All project documents use the same Best Practices for the title page of the document. Follow this link to find the Title Page Best Practices.

  1. Introduction
  2. All project documents use the same Best Practices for the Introduction/Overview section of the document. Follow this link to find the Introduction Best Practices.

  3. Design

 

2.1 Overview

2.1.X Class Diagram

Class diagrams are in UML format. Please see the Rational UML quick reference page for the symbols to use in the class diagram.

If there are classes shown in the Class Diagram that are an interface to this design but are not directly part of the design appear with a gray background. Classes that are directly part of this design have a white background.

2.2 <ComponentX>

Package in the software system there should be a subsection. If the design consists of only one component then skip this suction level and go directly to the Class subsections.

2.2.1 <ClassX>

For each class in the component there should be a subsection. If the class is part of an API then a reference to the corresponding Specification Document must be present.

3.0 Glossary

All project documents use the same Best Practices for the Glossary section of the document. Follow this link to find the Glossary Best Practices.

4.0 Change Log

All project documents use the same Best Practices for the Change Log section of the document. Follow this link to find the Change Log Best Practices.


Leon S. Searl

Last Modified: 2001-01-17