We do a fair amount of technical due diligence work, and one thing we see over and over again is infrastructure documentation.

Or, more accurately, the lack of it.

By infrastructure documentation I mean how the system is wired together: networks, services, data stores, deployment. Not software architecture, which is a separate problem with separate answers, and where diagrams still earn their keep.

The traditional answer is pretty straightforward: write good documentation. Keep it extensive, clear, searchable and accessible. Have architecture diagrams. Explain the networking. Document the deployment process. Keep everything up to date.

Sounds great.

Now try keeping it up to date.

Infrastructure changes every week. Sometimes every day. Someone clicks a button in the cloud console. A Terraform module gets changed. A temporary workaround becomes permanent. Six months later, the architecture diagram is confidently explaining an infrastructure that no longer exists.

The problem is not that teams don't know how to write documentation. The problem is that documentation is another thing that needs maintaining.

And infrastructure already has something that is much better at describing itself: the infrastructure itself.

Terraform is documentation

If your infrastructure is properly defined in Terraform, you already have a remarkably detailed description of how your system is put together.

Networks, databases, queues, permissions, load balancers, DNS, instances, buckets, secrets and all the delightful little dependencies between them.

More importantly, it changes when the infrastructure changes.

That makes it a much better source of truth than a wiki page someone last touched in 2023.

Of course, Terraform isn't the whole story. There can be drift between what Terraform says should exist and what actually exists in the cloud. There are also plenty of important things that Terraform won't tell you, such as why a weird architectural decision was made in the first place.

So the ideal setup isn't "put everything in Terraform and throw away the wiki".

It's closer to:

Infrastructure as code + automated discovery + a small amount of useful human context.

Make the infrastructure queryable

This is where things get interesting.

Instead of generating yet another 47-page architecture document, give engineers and auditors tools that can inspect the infrastructure and answer useful questions.

Things like:

Show me how a request gets from the internet to the application.
Which resources are publicly accessible?
Where is customer data stored?
What happens if this database goes down?
Which services depend on Redis?
Find infrastructure that exists but isn't managed by Terraform.
Why does this service have access to that bucket?
What's different between staging and production?

These are much more useful questions than "Can you send me the latest architecture diagram?"

And because the answers are derived from the actual infrastructure, they have a fighting chance of being correct.

Particularly useful for technical due diligence

This changes the way an infrastructure audit can work.

Today, an auditor might receive a collection of documents and then spend a considerable amount of time figuring out whether they are complete, accurate and still relevant.

With a well-structured infrastructure repository and the right tooling, the auditor can start probing the system directly.

Not by clicking around production with a pair of crossed fingers, but by querying the code and the actual cloud configuration.

It also gives you something much better than an architecture diagram: evidence.

If the answer is "this database is encrypted at rest", you should be able to see exactly where that conclusion came from.

That makes the tooling useful for auditors, rather than just a fancy way of producing documentation with more words.

Engineers get something useful too

This isn't just about making auditors happy.

A new engineer can ask:

How does deployment work?

A developer can ask:

What else will be affected if I change this network?

Someone investigating an incident can ask:

What depends on this service?

Someone making an infrastructure change can inspect the blast radius before touching anything.

Suddenly, the infrastructure repository isn't just a place where Terraform lives. It's a usable interface to the system.

That's a much more interesting proposition than another Confluence page.

There is still room for humans

There is one thing Terraform will never tell you:

why.

Why is this service running on a separate network?

Why are we paying for this unnecessarily large database?

Why is this weird-looking workaround still here?

Why should nobody touch that particular piece of infrastructure?

That knowledge still needs to live somewhere. Decision records are usually enough: a short note per decision, capturing why. They take discipline to write and almost no maintenance afterwards, because a decision made in 2023 stays made. If something was never recorded, the fallback is the same code archaeology you would have done anyway, except this time you write down what you find.

Keep those notes next to the infrastructure code rather than in a wiki. Same repository, small interlinked markdown files. Then the tooling that answers what can answer why in the same breath, because both live in the same place.

That documentation should complement the infrastructure, rather than attempt to recreate it.

The goal isn't to document every resource twice.

The goal is to make the infrastructure itself the source of truth, and document the bits that aren't obvious from it.

From documentation to interrogation

I think we're moving away from the idea that good infrastructure documentation means having a perfectly maintained collection of diagrams and wiki pages.

The better goal is to have infrastructure that can explain itself.

Terraform tells us what we intended to build.

Cloud discovery tells us what actually exists.

A handful of well-designed tools lets us ask questions about both.

And human documentation explains the bits that machines can't know.

That's a much more useful definition of infrastructure documentation.

And, thankfully, it means we can stop pretending that the architecture diagram from three years ago is "mostly still accurate".