While documenting, remember

There is a deceptively simple principle about documentation that most teams learn the hard way:

Clarity is important to support communication. Completeness and precision are needed to support analysis.

Read that twice. It contains a distinction that most documentation culture ignores.

Clarity and completeness sound like they point in the same direction—toward better docs. But they serve different readers doing different things. Clarity serves someone trying to understand quickly: a new team member reading a design doc, a stakeholder reviewing a proposal, a developer picking up a ticket. Communication is about reducing the time-to-comprehension. You achieve it by cutting noise, using plain language, and organizing for the reader’s mental model rather than the author’s.

Completeness and precision serve a different purpose. When someone is analyzing—auditing a decision, diagnosing a failure, verifying compliance, tracing a bug—ambiguity is expensive. A document that communicates well but omits edge cases or leaves requirements vague becomes a liability the moment someone has to rely on it for something critical. Precision means every statement has a determinable truth value. Completeness means the document covers the scope it claims to cover.

The failure mode in most projects is conflating these. Teams produce documents that are neither clear enough to communicate nor precise enough to analyze. They use technical language that slows comprehension without adding rigor. Or they write casually in a way that is easy to read but impossible to reason from.

Understanding the purpose before you write is not a small thing. A runbook entry needs clarity—the person reading it may be under pressure at 2 AM. A requirements specification needs completeness—the person implementing from it needs to be able to make decisions you won’t be around to answer. A postmortem needs both: legible enough that leadership understands what happened, precise enough that engineers can actually fix it.

Documentation done without this awareness accumulates as organizational debt. It takes up space without doing work.