Guidance is the human layer of API governance — the how-to and the why that sits alongside the machine-executable rules and gives people something they can actually read, understand, and act on. A rule is a check an engine runs; guidance is the explanation a human reads. I’ve come to believe that guidance is the most under-invested part of most governance programs, and also the part that determines whether the whole thing succeeds. You can write flawless rules and articulate crisp policies, but if you never explain them to the people expected to follow them — in language they understand, at the moment they need it — you’ve built a system that enforces without teaching. Guidance is where governance stops being a wall teams run into and starts being help teams reach for. It is the connective, human-facing member of the API Commons building-block family, and it’s the one I keep returning to because it’s where governance meets the person doing the work.
Guidance is one member of a family of governance building blocks — rules, policies, guidance, experiences, and the lifecycle — and the pieces only work when they work together, with policies as the hub that ties them to one another. I wrote in 2024 about bridging API rules, guidance, experiences, and the lifecycle using policies, and that framing is the heart of how I think about all of this: the policy is the connective artifact, and each of the other members plays a distinct role around it. Rules are the machine-executable checks. Policies are the business and human rationale that give the rules meaning. Experiences are the human outcomes the whole system is meant to protect. The lifecycle is the timeline that says when each thing applies. And guidance is the layer that translates all of it into human terms — the prose, the examples, the how-to that lets a person understand what a rule is asking and, more importantly, why. A rule without guidance is enforcement without education; guidance is what closes that gap.
The claim I keep making, and mean literally, is that good API governance is just guidance. Strip away the tooling and the ceremony and what governance actually does — when it’s done well — is help people make better decisions about their APIs. It guides. The rules and policies and engines are all in service of that guiding function; they’re the mechanism, but guidance is the point. When I explored where governance guidance is going in 2026, the throughline was that governance is converging on this human, explanatory center of gravity — that the future of governance is less about tightening the net of checks and more about getting the right guidance to the right person at the right moment. If your governance program produces compliance but doesn’t help anyone get better at building APIs, it isn’t really guiding, and it isn’t really governing well. It’s just policing. The measure of good guidance is whether the people who receive it come away more capable, not just more constrained.
Guidance should be guardrails, not gates. A gate stops you and makes you wait for permission; a guardrail keeps you on the road while you keep moving. That distinction matters enormously for how guidance is received, because gates train teams to see governance as an obstacle to route around, while guardrails train them to see it as support that lets them go faster with confidence. Guidance delivered as a guardrail says here’s the safe path and here’s why, and it leaves the team moving; guidance delivered as a gate says stop, and it breeds the resentment and workarounds that hollow governance out from the inside. The whole reason I lean so hard on guidance as the human layer is that it’s the form governance can take without becoming a gate — it can be present, helpful, and constant without ever being the thing that blocks the work.
And guidance has to be delivered inline and just-in-time, where the work actually happens, or it may as well not exist. I wrote in 2024 about my just-in-time API guidance kiosk precisely because the failure mode of guidance is that it lives in a wiki nobody opens, disconnected from the moment of decision. Guidance that arrives in the editor as you write the OpenAPI, in the pull request as you propose a change, in the CLI as you run a check — guidance at the point and time of the work — is guidance people actually use. Guidance filed away in a governance portal, weeks removed from the decision it was meant to inform, is guidance that guides no one. So the discipline of guidance is two-fold: get the human explanation right, and get it delivered to the exact place and moment where someone needs it. Do both, and guidance becomes the quiet, constant, humane layer that makes all the rest of governance legible and worth following — the layer where the machine-executable rules finally get explained to the humans they govern.
