A simple and efficient way to document or specify blackboxes are tables, like shown in the following sections.
Minimal Blackbox Template
| Purpose/Responsibility | <short description of purpose> |
| Interface(s) | <short description of interface(s)> |
Full Blackbox Template
| Purpose/Responsibility | <short description of purpose> |
| Interface(s) | <short description of interface(s)> |
| (optional) Quality-/performance characteristics | <short description or links to quality requirements> |
| (optional) directory/file location | where to find the source code of this blackbox. |
| (optional) Fulfilled requirements | <short description or links to requirements documentation> |
| (optional) Open issues | <list of known problems/risks, links to arc42-section 11> |
Remarks
-
Interfaces: describe those only when they are not extracted as separate paragraphs. Interfaces may include qualities and performance characteristics.
- Quality-/performance characteristics might be topics like availability, run time behavior, flexibility or similar.
- Directory/file location: This might be a single file/directory, or a list of sources making up this blackbox.
- Add fulfilled requirements only if you really need traceability. It’s expensive and creates huge effort… Think twice.