Documentation Is an Interface

Documentation is often treated as a narrative written after implementation. A more useful model is an interface between a system and the person who must operate, change, review, or recover it. Like any interface, it needs a defined audience, stable concepts, and a clear result.

Different documents serve different decisions. A readme helps someone orient and run the project. An architecture decision explains why one durable option was selected over alternatives. A runbook guides diagnosis and recovery under pressure. An API contract defines shapes and failure behavior. Combining all of them into one growing file makes every reader search through unrelated detail.

Write from evidence. Commands should be executable, paths should exist, and status claims should identify the check that proves them. Avoid copying configuration values that will drift when a canonical file can be linked. When a procedure has guarded or destructive steps, state the checkpoint and recovery plan before the action.

Good documentation also establishes vocabulary. If the code says publication, the database says product, and the interface says report for the same concept, ambiguity spreads across tests and conversations. A small shared language reduces translation cost and makes conflicting assumptions visible earlier.

Maintenance is part of the contract. Update documentation in the same change that alters behavior. Delete obsolete instructions rather than stacking a new warning above them. Review examples and screenshots when interfaces change, and keep generated reference material separate from authored operational guidance.

The best document is not necessarily long. It gives the intended reader enough context to choose and act without inventing missing steps. When documentation is designed as an interface, clarity can be tested: a fresh reader should reach the expected outcome, recognize failure, and know where authority lives. That is production behavior, not administrative polish.