Pattern Structure
Every pattern is documented following the same basic components. The idea is to have a simple and succinct documentation artifact that quickly explains, in plain English, what the thinking is behind certain design decisions, both at conceptual and technical level.
The key is to capture ‘the why’, as opposed to a deep technical view. It is often easier to understand the reasoning, and the technical details can always be viewed in code. Moreover, the thinking at the time of decision making is not captured in code and this is often the main context required to correctly evaluate design decisions over time.
Every Design and Solution pattern uses the following key elements:
- Title: a meaningful name of the pattern.
- Purpose: a short statement what the pattern is trying to achieve or explain. What is the intent of the pattern?
- Motivation: a short overview of the background and relevance of the pattern. Why is there a need for this?
- Applicability: a listing of where this pattern can be expected to play a role, the locations in the solution design. Where is it required? When and where is it used?
- Structure: the main section with the pattern details, the main content. This also includes any references to how to implement this pattern (Design Patterns only). Note that the Solution Pattern is intended to explain the specifics in a technical context. This is meant to capture any generic topics, thoughts and reasoning. The content is the how of the pattern.
- Implementation guidelines: highlighting any technical considerations. Ideally, a concrete example of how the pattern is applied. How is this pattern used in practice?
- Considerations and consequences: this section is meant to offer some alternative views and experiences as to what it means to take a certain decision. What are the known impacts?
- Related patterns.