Insight

An Interface Nobody Can Find

The expensive thing about an undocumented interface is not the missing document. It is that every single use of it now requires a conversation, forever, with someone who happens to hold the knowledge.

That conversation never appears as a cost, because it looks like helpfulness. Someone asked, someone explained, the work continued. Nobody logs it. But it happens again the next time anyone new needs the capability, and the next, and the total is never summed anywhere.

There is a second effect that compounds faster and gets noticed later. When nobody can see how a thing was meant to be used, everybody uses it slightly differently — and every one of those variations has to be supported afterwards. Undocumented interfaces do not stay simple. They become complicated because they were undocumented, which is close to the opposite of what the people skipping the documentation assumed.

The distinction most organizations get backwards is internal versus external. External interfaces get documentation, versioning, examples and someone who cares whether they are pleasant to use. Internal ones get a message and a name. The needs are identical — discover it exists, understand what it does, use it without booking a meeting. The only real difference is that internal consumers cannot take their business elsewhere, so they absorb the friction quietly and the organization never finds out what it is paying.

None of this is a software concern. A finance approval, a legal review, a procurement route: if the way to request it is not written down, you have to ask someone who knows. And asking someone who knows is the most durable friction generator there is, because it works just well enough that nobody ever fixes it.