Awesome Architecture Descriptions and Pattern Languages

My Frequently Accessed Venues (FAVs)

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

Architecture Description Formats

When it comes to documenting software architecture requirements and 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[1].
3. OpenUP seems to have lost weight in recent years[2]. 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”[3] elements such as user stories, SMART non-functional requirements and Architecture Decision Records (ADRs).

My blog posts (hopefully) have something to offer too:

• Criteria-based test of architectural significance of requirements and issues
• Definition of done for architectural decisions
• Y-statements as an Architecture Decision Record (ADR) format

Just in case you are concerned of the effort: in “Using Patterns to Capture Architectural Decisions”, Neil Harrison, Uwe Zdun and Paris Avgeriou teach us that patterns can cut it. So let’s compile links to some pattern languages now.

Pattern Languages

I only list some 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
• (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 patterns world. I apply and teach all of the above, but also others. Gregor Hohpe provides a rather comprehensive collection of reading recommendations for architects, organized into four book shelves.

Wrap Up

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

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)

PS: This story is also available on The Concerned Architect blog

© Olaf Zimmermann, 2020. All rights reserved.

Notes

[1] created by R. Hilliard, one of the authors of the standard
[2 ]where did the Software Architecture Document (SAD) go?
[3] quoting M. Keeling at ECSA 2020 here