Naohiro Nishiguchi

Blue italics are guideline for description.

Table of Contents

1. Executive Summary

Executive summary is an introduction to the document. Do not dig deep into the technical details, but provide a comprehensive overview.

• What is the purpose of this document?
• What is the position of this document?

2. Indexes and tables

2.1 Change history

2.2 Referenced documents

2.3. Glossary

3. Scope

This section gives the reader's context regarding the design documentation.

• What this design document applies to and what not (if needed)?
• What are the pre-requisites for the reader?
• Who are the intended reader of this? 

4. Use case

This chapter describes the intended behavior of the software architecture and/or component under design by describing a certain usage of the component.
Use cases provide an initial view on the feature and they should set the scope of the design.
The description includes;

• the external parties that interact with the component or that the component interacts with and
• the operational scenarios which might impact the functionality of the component.

Use cases should describe the essential behavior instead of every detail. 
Use cases may be layered in the description. ( e.g., you can decompose a feature and break it down into detailed use cases.)

Below table is a sample for use case description.

5. Requirements

This chapter shows functional and Non-functional requirements to be designed.
If there are any constraints to design, please describe them as well.

6. Architectural design

6.1. Design Consideration

Describe the key design decisions and the reason.
Design decisions are usually carried out in order to fulfill quality attributes, that are might be described as non-functional requirements in previous chapter, that are appropriate for architecture and/or component.

• Which design options are considered and/or chosen? why?
• What quality attributes are relevant/important for the design?
• How such attributes are exhibited in the design?

6.2. External view 

Component under design should be seen as a black-box in diagram. Logical and process views should explain how the component is interacting with the rest of the system.

• Logical view shows the static aspects of the architecture, such as the following diagram
  • component structure diagram, class diagram, object diagram
• Process view shows the dynamic aspects of the architecture, such as the following diagram
  • inter-component sequence, generic activity diagram, state machine diagram.

7. Interface definition

Interface, that includes data and function/method, provided by this component to be used by other components is described here.

• For the data, followings should be defined.
  • the command protocol, structure
  • the structure of the data being exchanged
• For the function/method, followings should be defined.
  • function/method name and role
  • argument and its meanings
  • return value type

If there are some restriction to use (e.g. order of use), they should be described with some diagrams.
Configuration parameter and/or configuration files also should be described here, if needed.

8. Component details

8.1. Other component

Describe the components that are related to the components under design.
It is recommended that the relevant components be described alogn with the interfaces used by the component under design to make the impact analysis more efficient.

8.2. Designed component

the component under design is seen as white-box.
If there are multiple components to be designed, please repeat from section 8.2.1 to 8.2.3 for the number of designed components.

8.2.1 Requirements

This section shows functional and Non-functional requirements to be designed in component level.
If there are any constraints to design, please describe them as well.

8.2.2 Logical view

Please refer Section 6.2

8.2.3 Process view

Please refer Section 6.2

8.3 Deployment view

Component may have sub-parts and these sub-parts are packaged as different distributable units. Explain them here.