Awesome Architecture Descriptions and Pattern Languages

This “meta-post” points you at valuable templates for documenting software architectures as well as a few pattern languages that can support their creation.

Architecture Description Formats

When it comes to documenting designs, some of my most frequently visited resources are:

1. The twelve-section arc42 template “takes the pain out of documentation” and is accompanied by many hints.
2. ISO/IEC/IEE 42010:2011, defining what frameworks are and making the case for capturing decision rationale. There is a template to ease the creation of 42010-compliant architecture descriptions.¹
3. OpenUP seems to have lost weight in recent years.² But it still is a good place to look for guidance. For instance, try the “Architecture Notebook” under “Guidance” and then “Checklists”.
4. The SEI assets run under Views and Beyond and include the book “Documenting Software Architectures” by Felix Bachmann, Len Bass, Paul Clements et al.
5. (disclaimer: my own) Design Practice Repository (DPR) is an open source repository collecting “mighty method”³ elements such as user stories, SMART non-functional requirements and Architecture Decision Records (ADRs).

My blog posts here and on Medium have some checklists and templates to offer too:

• Criteria-based test of architectural significance of requirements and design issues
• Definition of done for architectural decisions
• Y-statements as an ADR format

You still think documenting is tedious? In “Using Patterns to Capture Architectural Decisions”, Neil Harrison, Uwe Zdun and Paris Avgeriou teach us that patterns can cut the effort. So let’s compile links to some pattern languages now.

Pattern Languages

I only list very few (per viewpoint) here, only those that make content summaries available online:

• Analysis and design of business logic: Domain-Driven Design (DDD)
• Logical architecture, all layers: Patterns of Enterprise Application Architecture (PoEAA)
• Integration and messaging (process viewpoint): Enterprise Integration Patterns (EIP)
• Deployment (to the cloud): Cloud Computing Patterns (CCP), patterns such as Loose Coupling and Three-Tier Cloud Application also contain valuable advice for on-premises deployments (despite the name of the latter)
• (disclaimer: led by me) Microservices and API design: Microservice API Patterns (MAP)

This list is certainly incomplete; please merely view it as my personal entrance door to the (enterprise application) patterns world. I apply and teach all of the above, but also others.

Wrap Up

This post collected pointers to five architecture description frameworks, standards, templates, guidelines, checklists. It also suggested patterns and pattern languages, available online, that can get you started with architecture design.

Gregor Hohpe provides a rather comprehensive collection of reading recommendations for architects, organized into four component-oriented book shelves. My Blog Index provides many additional pointers, to all posts in this blog but also those of other bloggers.

Which notations and patterns do you use to solve domain-specific and general design issues? How do you document the design decision outcomes? Tell me!

– Olaf (a.k.a. ZIO)

This post is also available on Medium.

Notes