What principal engineers document

Documentation that scales

At senior levels, documentation is less about completeness and more about leverage. You document decisions that reduce future ambiguity.

Good docs shorten onboarding time, reduce design drift, and make high-pressure changes safer.

Four docs that matter most

Decision records: what changed, why alternatives were rejected, and what assumptions exist.

Interface contracts: schema guarantees, versioning rules, and deprecation windows.

Runbooks: operational actions for common and severe failure paths.

Migration notes: rollout stages, validation checks, and rollback instructions.

type ServiceHealth = {
  service: string;
  latencyP95Ms: number;
  errorRate: number;
};

export function shouldPageOnCall(input: ServiceHealth) {
  const highLatency = input.latencyP95Ms > 450;
  const highErrors = input.errorRate > 0.02;
  return highLatency && highErrors;
}

Operating principle

Write for the engineer who is new to the system and under time pressure. If the doc helps them make the right call quickly, it is successful.