Are You a Well-Documented API?
13 May 2026
"I'M not the loudest in the room."
Something a lead engineer told me recently. The kind of developer who designs and strategises architecture underneath a whole team. Not a junior finding their feet. Someone senior, trusted, technically excellent.
But that wasn't really the problem.
The problem was this: he'd share his thinking openly. Collaborate on the tradeoffs and contracts. And BAM, once in place the manager usually got the credit.
This problem got me thinking...
Every Team has an API that isn't Code
Every engineering team has its own API. I am not talking about a codebase, either. A team is a unit in a business that has an outward facing interface. Directors, stakeholders, other teams interact wit this API and don't see the internals. They have nice, tidy endpoints to interact with the team.
Someone is always writing the docs for that API.
For the most part, that someone is the manager.
They take the team's output and route it through the API back into the business. They summarise it. All the grisly technical detail is translated into clean metrics and KPIs. They advocate for it, or they don't. They attach names to it, or they don't.
Developers are often happy to be an internal service, abstracted from the world of the business.
As a consequence, like any undocumented internal, they are invisible to the consumer.
The Law of Demeter
This is probably not a grand conspiracy to keep developers down. It's the principle of least knowledge. There's no need for external teams to be reaching deep into the internals of development. It's an org smell.
On the contrary, I've seen the damage this can do to effective software development.
We are better off assuming that the people closest to the work understand it best. As the work of engineering and organisational strategy are undertaken by wholly different people, there is always a translation layer between value creation and value recognition.
"Who controls the translation layer controls the influence."
When a developer shares their thinking generously: bringing tradeoffs, alternatives, contracts, they are being collaborative. They are being professional. They are doing the right thing technically.
But unless they also own the translation, they are losing the influence they could have gained.
The Point of Leverage
The moment where the influence has been assigned is much earlier than we suspect.
A retroactive "good work" after shipping rarely does justice to the contribution of a senior, or lead developer.
Usually the decision is made as part of a messy internal---a PR comment, some archived ticket, an in-person meeting---the influence internally is created here.
However, it is shared organisationally during a status update, a board meeting, a strategy session. Rarely, is the primary source cited.
That is the moment that the communication happens. And it doesn't involve the internals of the system at all. It's an abstracted, packaged version from the translation layer.
The Undocumented Endpoint
This is not generally visible to developers because it is often a harmonious arrangement for shipping a quality product. Not everyone is talking to everyone.
But undocumented functionality is quietly overlooked. A slight frustration when a colleague gets recognised for something you contributed to. A sense that your manager likes you but never quite advocates for you. Performance reviews where you are solid but somehow not quite ready for the next level. It might even be when there are strong disagreements in the internals where one party holds a lot more influence.
And to developers, these often don't feel like 'communication issues' at first. They might feel like 'office-politics' (honestly same thing). They might feel like a bad culture.
Truthfully, they are interface problems where the docs are not properly updated by the maintainer.
Noticing this is the first step. If there are signs that your work is too internal, keep looking. It's likely that you are too removed from defining the API contract of your organisation.
Becoming a contributor to that contract is engineerable. If you want to know how, book a call.