Architecture Documentation: Where to Draw the Line?

Introduction

Architects really care about taxonomies. I.e. unambiguously classifying, decomposing and grouping things. It is at the heart of how architects go about carving up problems — and solutions to these problems — into repeatable patterns and reference architectures. And yet — ironically — there are a couple of things that are often poorly understood in the architecture world:

• The role and responsibilities of an architect. (I’ll cover this another day.)
• What belongs in architectural documentation.

I’m going to cover the latter here!

Problem Statement

If your job title is Systems Architect, Solution Architect, Cloud Architect or Technical Architect, you will no-doubt have been asked to produce some sort of architecture design documentation, scoped to the delivery of some sort of system or solution. This architecture design document has many names, including:

• High Level Design (HLD)
• System / Software / Solution Architecture Document (SAD)
• Technical Design Document (TDD)
• Architecture Design Document (ADD)
• Technical Architecture Document (TAD)