Skip to main content

Functional Description and Detailed Design Guideline

This guideline describes how to write Functional Description and Detailed Design documents.

Introduction​

More information about what to describe needs to be decided by each stream/product, a template is recommended. They can be described in different formats, but md-files are preferable for new documentation. The figure below is an overview of different kinds of documentation and how they relate to other kind of documentation.

Overview documentation

Functional description​

Function description shall, if needed describe functionality with more details than the capabilities. The functionality can be described only in capabilities, if suitable. The functional description can also include other valid information about for example performance, scalability, maintenance, etc.

Detailed design​

Detail design descriptions are mandatory. Describe for example how different code modules and classes within the component interact. Describe the public interfaces of the component.

Purpose and scope of​

Purpose and scope for Functional description​

Functional descriptions can describe more details than the capabilities, which usually is a bullet list with short descriptions. Described so that other stakeholders than developers, such as product owners, testers, and user documenters can understand the functionality.

Add the architectural modeling structure and dynamic behavior in the detailed design.

Purpose and scope for Detailed design​

Detailed design shall describe the structure and design of components/modules. It is important to describe the complex design parts, that will help developers to understand the code in the future. Cyclomatic complexity or other measurement can be used to decide the complexity.

  • It shall not describe code details that can be understood when reading the code.
  • It shall also help developers to understand when safety and security are relevant.
  • It shall also be helpful for other teams, and new developers to get an overview of the code.

Modeling in detailed design​

Modelling is optional, except for safety. It is up to each stream/product/component to decide if they shall do any modeling. If modeling is done, plantUML-diagrams together with md-files are preferable.

The streams should create a guideline/template for how to model, which diagrams to use, and what is mandatory.

Traceability​

Functional description for traceability​

It shall be possible to find a more detailed description from the capabilities, one way could be to use a link to the md-file where the functionality is described.

It may also be helpful to find the relevant capability bullet from the functional description.

Detailed design for traceability​

There shall be traceability to the relevant functional description. The stream architecture team together with the teams that do the detail design modeling have to decide how the architecture models are connected/traced from/to the detail design models.

Security​

For security, there is a checklist to follow.

Owner: Software Development Team