Documentation Is Infrastructure (Just Made of Text Instead of Routers)

The views expressed here are my own and do not represent those of any current or former employer.

I once spent three months writing a single document. Not code. Not a Terraform module. A document.

It was a foundational technical design document for how our organization should structure, deploy, and scale a multi-account cloud environment. It specified baselines, guardrails, and patterns that teams could follow for years. When I finished, some people asked if I’d been underutilized. Shouldn’t a senior engineer be building things?

I was. I just built it out of text instead of routers.

The Problem Documentation Solves

Here’s what happens without foundational architecture documentation: every new team reinvents the wheel. They make the same mistakes the last team made. They design a solution that works for their use case but creates problems for the next three teams. And nobody notices until the inconsistencies compound into operational pain.

I’ve seen this pattern at multiple companies. The first team to build in a new account does it one way. The second team does it differently. By the time you have ten teams, you have ten incompatible approaches, and the infrastructure team spends all their time debugging the differences instead of building the next capability.

Documentation prevents that. Not because people love reading docs — they don’t — but because a well-written specification becomes the default. When someone asks “how should I set this up?”, the answer is “read the blueprint.” When someone proposes a deviation, the conversation starts from a shared baseline instead of from scratch.

What Makes Documentation Infrastructure

Infrastructure has three properties: it’s shared, it’s durable, and it shapes what’s possible on top of it. Good documentation has all three.

Shared. The blueprint I wrote wasn’t for my team. It was for every team that would ever deploy into our cloud environment. Security referenced it for compliance reviews. IT used it for account provisioning. New engineers read it during onboarding. A single document, used by dozens of people with different needs.

Durable. Code changes constantly. Documentation that captures principles lasts. The specific Terraform modules I wrote that year have been modified many times since. The architectural principles in the blueprint — the reasoning behind subnet sizing, security group patterns, and account isolation strategies — those still hold. When someone asks “why did we do it this way?”, the blueprint has the answer.

Shapes what’s possible. A good architecture document doesn’t just describe the current state. It defines the boundaries of safe decisions. “You can do anything within these guardrails” is a more scalable message than “ask me before you do anything.” The blueprint gave teams the confidence to move fast because they knew the safe zone.

The Multiplier Effect

Think about it in terms of time saved. If the blueprint prevents even one team per quarter from spending two weeks figuring out the right VPC layout, that’s eight weeks of engineering time saved per year. Over three years with ten teams referencing it, the math gets significant.

That’s the same kind of leverage that a good internal tool or platform provides. You invest upfront, and the returns compound as more people use it.

And unlike code, documentation requires almost no maintenance. You update it when the architecture changes, which is infrequent if you designed it well. There are no dependency upgrades, no security patches, no CI pipelines to maintain. It’s the lowest-maintenance infrastructure you can build.

How I Write Architecture Docs

I treat architecture documentation like I treat infrastructure design: start with the constraints, make the tradeoffs explicit, and optimize for the reader who will use it six months from now without talking to me first. Over time I’ve landed on four principles that separate documents people actually use from documents that quietly collect dust.

Start with the “why.” Before any technical specification, explain why this architecture exists. What problem it solves. What alternatives were considered and rejected. This context is what prevents people from making well-intentioned changes that break the design’s assumptions.

The failure case looks like this: a team encounters the document, decides the subnet sizing feels conservative, and “optimizes” it without understanding that the sizing was intentional — it preserved address space for a future peering arrangement already in motion. If the document had explained why the subnets were sized that way, the team would have had that context before changing anything. Context is not optional decoration. It’s the part of the document that survives the longest.

Be opinionated. A document that says “you can do it several ways” is useless. A document that says “do it this way, and here’s why” is infrastructure. Teams don’t want a menu of options. They want a recommendation they can trust.

This is harder to write than it sounds. Offering options feels humble and inclusive. It also means nobody knows what to actually do. When I write architecture documentation, I make a choice, I name the choice, and I defend it. Engineers who disagree know exactly what they’re disagreeing with, which makes the conversation productive rather than circular.

Include the escape hatch. Being opinionated doesn’t mean being inflexible. Good architecture docs specify the default path and the process for deviating when you have a legitimate reason. “If your use case doesn’t fit this pattern, here’s how to propose an exception.” That prevents the doc from becoming a bureaucratic gate. Without an explicit escape hatch, teams who hit the edge of the standard either quietly go rogue — making changes they don’t document — or stop moving entirely because they don’t know how to ask permission. Both outcomes are worse than a well-defined exception process.

Write for the person who disagrees. The hardest reader isn’t the one who wants to follow the doc. It’s the senior engineer who thinks they know better. Write for them. Address the objections they’ll have. Explain the tradeoffs they’re thinking of. If you can convince the skeptic, everyone else will follow.

I have a specific technique for this: before I finalize any architectural recommendation, I try to write the strongest possible objection to it. Not a strawman — the real objection, the one a thoughtful engineer would actually raise. Then I either address it in the document or I reconsider the recommendation. If I can’t defend the choice against a smart challenge, the choice probably isn’t ready to be a standard.

What a Principled Architecture Doc Opening Looks Like

The first section of any foundational architecture document does the most work. It’s where you establish context, scope, and authority. Here’s the skeleton I’ve landed on:

## Context and Motivation

[2-3 sentences on the operational problem this document solves.
Not "we need standards." Specifically what breaks without them.]

## Scope

This document covers [specific system/layer/boundary].
It does not cover [explicit exclusions with rationale].

## Assumptions

- [Constraint that shaped the design]
- [Constraint that shaped the design]
- [What's expected to remain stable vs. expected to change]

## Decision Summary

[Table or list: the 3-5 most important choices, with one-line rationale each.
Readers can scan this before deciding how deep to go.]

## Alternatives Considered

[At least one rejected path with an honest reason for rejection.
This is what prevents the "why didn't we just..." question two years later.]

That structure is not a template to copy wholesale — it’s a checklist of questions to answer before the technical specification begins. Without it, architecture documents tend to open with a system diagram and no context for why the diagram is shaped the way it is.

The Lesson

Organizational entropy always tries to turn standards into optional suggestions. Code rots. Practices drift. Tribal knowledge leaves with every departure.

Documentation is the counterweight. It’s how you encode decisions so they survive past the people who made them.

There’s a version of this argument that stops at “documentation is leverage” and leaves it at that. I want to push further: the discipline required to write good architecture documentation — making explicit choices, defending tradeoffs, writing for the skeptic — makes you a better engineer even before anyone reads the document. You can’t write clearly about an architecture you don’t fully understand. The writing is how you find out what you actually know.

If you write it well enough, it’s the highest-leverage infrastructure you’ll ever build.