Describe as a Whitebox the elements of a view where only the relations of internal elements are relevant.

ID
whitebox
Suite
Documentation Type
Categories
Tags

The Whitebox View provides information about the elements of an element and their interaction.

For many Blackbox Views there is a Whitebox View to complete the understanding of the element.

The idea is to document a service that is built from a number of Components. Often this is enough to give a reader a good understanding what this service is about. Sometimes you want to drill deeper. Then you show the interfaces of a component in a Blackbox. You concentrate on the behavior that can be observed from the outside. Next you step into this component and document all the components on the next level inside this component detailed in the Blackbox. This documentation in the Whitebox document shows how the subcomponents work together inside the component.

In case you need to drill further into the components, you then describe each of the elements in the Whitebox View by a separate Blackbox document. Continue until everything you want communicate is in the alternating Blackbox / Whitebox documents.

Using the alternating Blackbox and Whitebox documents makes it easier to separate the documentation of the interaction of a component with its environment (Blackbox) from the documentation of the interaction of the subcomponents of the immediate next level.

If your design is not very deep, the documentation of a component may be enough. The Blackbox / Whitebox documentation simply allows to clearly communicate, what the focus of the individual document is.

Properties

The document type Whitebox provides the following properties:

Level

The level of the blackbox inside the hierarchy.

If you have added a whitebox view as a subdocument to a blackbox view and then add references to blackbox views for each element of this view, you get an alternating hierarchy of blackbox and whitebox views.

The level represents the number of whitebox levels.

Reference

A reference to an external documentation for the element this whitebox view is about.

Sections

Description

Give a summary on the whitebox.

Diagram

Add a diagram to describe the whitebox's interals.

Blackboxes

Provide information on the blackboxes inside this element. This is the explanation of the elements you show in your diagram.

Internal Interfaces

List the interfaces relevant to the internal elements. The interfaces are not exposed, otherwise they would be documented with the parent blackbox view.

Architecture Decisions

Document the important decisions concerning the structure of this element.

Special Dependency Issues

Discuss selected complex dependencies of the local building blocks.

Open Issues

List issues that still need to be resolved.

Details

This doctype is based on the whitebox template described in the chapter 5 of the arc42 Template.

Resources

Blackbox
Describe as a Blackbox the elements of a view where only the externally visible properties are relevant.
Component
Components are part of a view on a system. A component may refer to a enclosed element or to a complete system of its own.