The Paper Trail of IT Delivery
Purpose of this Guide
This guide is a practical framework for structuring, writing, and delivering architectural design documents across enterprise project engagements. It provides a standardized approach to ensure architecture teams create targeted, high-impact documentation that bridges the gap between strategic business objectives and physical IT infrastructure.
The Guiding Principle of Architectural Documentation
Just as diagrams are targeted communication tools, design documents are authoritative baselines. A document is only successful if it provides the exact level of detail required by its intended audience.
The biggest mistake architecture teams make is a failure to control a document’s depth—something I’ve certainly been guilty of in the past. Cramming granular server configurations and routing tables into a High-Level Design is just as destructive as handing a vague, conceptual capability map to a deployment engineer.
This guide empowers architects to establish strict vertical boundaries between the High-Level Design (HLD), the Solution Architecture Document (SAD), and the Low-Level Design (LLD). It clearly defines what each document is for, the primary stakeholders it serves, what goes inside, and—crucially—what to leave out to prevent document bloat and scope creep.
Defining the Boundary: The “Mega-Doc” Mistake
Controlling the depth of your design is only half the battle; you must also control the width. Early in my career, during a complete greenfield deployment, I attempted to document the entire underlying infrastructure and every hosted business system within a single Low-Level Design.
It was a disaster. The document became an unreadable, unmaintainable monster where a single firewall change required up-versioning a 200-page file.
Design documents must have strict horizontal perimeters. A document should encompass a single logical service, a specific technical domain (e.g., Core Network, Compute Cluster, Identity Management), or a defined project phase. If you are trying to capture the entire IT estate in one file, you are no longer writing a design document—you are writing an encyclopaedia, and it will be out of date before you finish typing it.
The Matrix: Document Rules vs. Diagram Rules
The rules for these documents work in concert with the “When to use” rules defined in the Architecture Diagram Playbook. One does not override the other.
If the Playbook states a diagram should be omitted for a specific scenario (e.g., skipping a Conceptual Data Diagram for a COTS deployment), do not force it into the design document just to fill a blank section.
Furthermore, diagrams across these documents are often “progressively elaborated.” This means you might include an Application Communication Diagram in your HLD to show broad logical boundaries, but you will intentionally wait until writing the SAD to update that exact same diagram with granular firewall ports and protocols.
