Describe as a Blackbox the elements of a view where only the externally visible properties are relevant.
- ID
blackbox- Suite
- Documentation Type
- Categories
- Tags
The Blackbox View provides information on how an element interacts with its environment.
The internals of the element are not revealed in this view. This would be the task of the Whitebox View.
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.
In case you also need to document your services in the context of operations, have a look at Doctypes for Service Management. This is a different view on services, but you may easily reference from a service to it's implementation if the readers of your documentation need to understand both domains.
Properties
The document type Blackbox provides the following properties:
Please note that only information about specific properties is provided here. Common document property used by all document types are documented by Document Properties.
Whitebox
A reference to the whitebox view that allows a look inside this blackbox.
Typically the whitebox view is a subdocument of this view.
Level
The level of the whitebox inside the hierarchy.
If you add a whitebox view as a subdocument to this view and then add references to blackbox views for each element of the whitebox view, you get an alternating hierarchy of blackbox and whitebox views.
The level represents the number of blackbox levels.
Sections
Notes
These are internal notes that are usually not exported and only visible to team members with write access.
But this is not a safe place to store sensible information. It is just a convenience for the reader to not be bothered with notes stored here for the authors for later use. The security level is about suppressing the representation by a CSS style. Therefore consider this as a convenience for the reader, not as a security tool.
The text of notes sections is also indexed.
References
For a document the references section contains pointers to resources that prove the statements of the document.
Often these proofs are not easily distinguishable from further information. In this case you may want to skip the reference section in favour for the resource list.
For further information please refer to References and Resources.
Resources
The resources section provides references to further information to the topic of the document.
This may be information on the internet provided by the resource or information in the team's information systems. Anything the reader of the resource might want to know, may be listed here.
For further information please refer to References and Resources.
Details
This doctype is based on the blackbox template described in the chapter 5 of the arc42 Template.