Why Documentation Is About to Matter Again

Documentation has a reputation problem. It is seen as overhead — something you write because you have to, not because it creates value. The best engineers write code. The less talented ones write documentation. This is the prevailing attitude in most engineering organizations, and it is about to become very expensive.

Why Documentation Failed Before

Documentation failed for structural reasons, not cultural ones. It was effort-intensive to write, hard to keep current, and difficult to search. The ROI was unclear because the payoff was always in the future — when someone needed to understand a decision that was made months ago.

As a result, documentation atrophied. Teams stopped writing it. New members learned from code and from asking teammates. Knowledge became tribal and fragile. This worked because the fallback was always "ask the person who was there."

What Changes with AI

AI fundamentally changes the economics of documentation.

First, AI makes documentation useful. A well-written architecture decision record becomes something the AI can read, index, and answer questions against. It becomes a first-class input to organizational intelligence. Documentation is no longer a reference you might read someday — it is a live knowledge source that your AI systems use every day.

Second, AI makes documentation easy to produce. AI can draft documentation from code, from pull request discussions, from incident timelines. The human's job shifts from writing documentation to reviewing and validating it — which is faster and more accurate.

The New Documentation Flywheel

The organizations that are solving documentation have found a virtuous cycle:

1. AI generates documentation drafts from code and conversations

1. Humans review and validate the drafts, adding context AI cannot infer

1. AI indexes the validated documentation and uses it to answer future questions

1. The more documentation exists, the better the AI's answers become

1. The better the AI's answers become, the less time humans spend answering the same questions repeatedly

This changes the incentive structure. Documentation is no longer effort spent for uncertain future benefit. It is effort spent today that compounds — because every piece of validated knowledge makes every future AI interaction more accurate.

What Makes Documentation Valuable to AI

Not all documentation is equally useful to AI. The most valuable documentation for AI consumption has three characteristics:

1. Structured: Clear sections, consistent formatting, explicit decisions with rationale

1. Contextual: Why a decision was made, not just what was decided

1. Linked: Connections to related decisions, systems, and incidents

The best format for AI-friendly documentation is the Architecture Decision Record. Each ADR captures a decision, the alternatives considered, and the rationale. AI systems can ingest ADRs and reason about them in ways that free-form documentation does not support.

The Practical Start

If you want to make your organization's documentation AI-ready, start with your ADRs. Even if you only have a few, make sure they follow a consistent format. Then ask your AI assistant to answer questions against them. The gap between what the AI can answer and what people ask will show you exactly where to write next.

The Uncomfortable Truth

In the AI era, documentation is not overhead. It is infrastructure. The organizations that invest in it will have AI systems that understand their context, their history, and their constraints. The organizations that do not will have AI systems that are generic — and generic AI is increasingly indistinguishable from commodity.

If your AI assistant could read every decision your organization has ever made, how many questions could it answer without escalating to a human?

Think this argument fits your event? Tell me about the room — the calendar is selective.