Less to think about: reducing cognitive load for developers

"You build it, you run it." I believe in that idea. Teams that own their services in production build better software. But somewhere along the way, "you run it" turned into "you need to understand Kubernetes, Helm, Terraform, IAM, networking, observability, security scanning and three CI systems". That's a lot to carry on top of actually building the product.

That weight has a name: cognitive load.

What cognitive load means at work

The idea comes from psychology, and the book Team Topologies made it popular in software. Every person and team has limited mental capacity. If too much of it is used on things that aren't their main job, their main job suffers.

There are roughly three kinds:

• Intrinsic: the complexity of the problem itself. Building a payment system is hard. That's fine.
• Extraneous: complexity that doesn't need to be there. Confusing tools, unclear processes, twelve ways to deploy.
• Germane: the effort of learning things that make you better at your job.

A platform team's job is to remove as much extraneous load as possible, so developers can spend their energy on the intrinsic and germane kinds.

If your developers need to understand your whole infrastructure to change one line of code, the infrastructure is the problem.

Hiding Kubernetes, gently

Kubernetes is a perfect example. It's powerful, but a simple web service needs a Deployment, a Service, an HTTPRoute or Ingress, a ConfigMap, maybe a HorizontalPodAutoscaler, a PodDisruptionBudget, a ServiceAccount, NetworkPolicies... Most developers don't need to know all of that.

Ways to reduce it:

• A shared Helm chart with good defaults. The developer's values file is fifteen lines instead of three hundred.
• Higher-level specs like Score (a workload spec that describes what a service needs, not how to deploy it), or Kro and Crossplane to build your own simple App resource.
• Templates that generate everything once, so developers start from something that works.

The word "gently" matters. Don't hide Kubernetes so completely that debugging becomes impossible. Make the simple path simple, and keep the details available for people who need them.

Good defaults beat good documentation

Every decision you ask a developer to make is a small piece of load. Most of them have a sensible answer that's right 90% of the time.

Bake those answers into the platform:

• Logs in a structured format, shipped automatically.
• Metrics and tracing set up in the base image or library.
• Resource requests and probes with reasonable values.
• Security settings: non-root containers, read-only file systems, dropped capabilities.
• Alerts for the basics: error rate, latency, restarts.

Documentation still matters, but the best documentation is the one nobody has to read because the default is already right.

Signs your platform makes it worse

Platform teams can increase cognitive load too. Watch out for:

• Another tool to learn that only the platform team really understands.
• Abstractions that leak: when something breaks, developers have to understand both the abstraction and everything underneath.
• Too many choices: "you can deploy with option A, B, or C" isn't self-service, it's homework.
• Constant change: a new way of doing things every quarter.

Ask developers regularly what slows them down. If the platform appears on that list, take it seriously.

So, how do you start?

Pick one area where developers struggle the most, often deployment configuration or observability. Reduce the number of things they need to know there. Measure whether questions to the ops team go down. Repeat.

My take: the best platform is the one developers barely notice. They just ship, and things work.

— Desly