Stop Telling Me What the Code Does. Tell Me Why I Should Care.

By Milton Harris on May, 2026. Posted in Uncategorized.

Engineer staring blankly at a screen full of code

I’ve been reading tech articles for twenty years, and I’ve hit a wall. I can’t stomach another 2,000-word piece that meticulously catalogs every parameter of a JavaScript method, lists all the accepted data types, and then slaps on a code block copied directly from MDN. That isn’t an article. It’s a reference page with delusions of grandeur. It tells me what. It never, ever touches why.

This problem is everywhere. It infects company engineering blogs, personal dev diaries, and the big tutorial mills that dominate search results. You search for “how to use React’s useMemo” and you get ten pages that all say the same thing: “useMemo accepts a function and a dependency array. It returns a memoized value.” Thanks. I can read the docs. What I can’t read in the docs is the mental model I need to stop wrapping every single variable in my component with useMemo and creating an unreadable disaster. The docs won’t tell me that I’m probably solving a problem I don’t actually have. A good article would.

The Hollow Shell of a “What” Article

Let’s dissect the typical offender. It usually starts with a friendly, generic introduction: “State management is a core concept in modern frontend applications.” No argument there, but it’s also a sentence with zero informational content. Then we move to the installation command: npm install some-library. Groundbreaking. Then we get a block of code, maybe 30 lines, with inline comments that just translate the syntax into English. // this maps over the array sits right above .map(). I can see that. My eyes work.

This format treats the reader like a compiler. It assumes my only job is to ingest syntax and spit out a working application. It ignores the fact that I am a human being trying to build a mental map of a system. I need to know about the trade-offs. I need to know when this tool was the wrong choice for the author and they had to rip it out at 2 a.m. That’s the stuff that sticks. That’s the stuff that saves me from making the same mistake.

The worst part is that these articles aren’t technically wrong. The code runs. The method signature is accurate. The output matches the description. But the entire piece is a pedagogical dead end. It equips me to solve the exact, contrived example on the page and nothing else. As soon as I hit the messy real world, with its legacy constraints and weird business logic, the knowledge vaporizes. I’m left with a snippet I can’t adapt because I never understood the principles underpinning it.

Code as an Argument, Not a Decoration

Kai Lindström doesn’t write code examples to show you the syntax. I write code examples to prove a point. There’s a fundamental difference. If I’m arguing that a particular pattern leads to untestable spaghetti, I’m not going to show you a pristine, happy-path implementation. I’m going to show you the ugly version first. I’m going to let you feel the pain of trying to mock that deeply nested dependency. Then I’ll show you the refactored version, and the contrast will be the argument itself.

Let’s take a concrete example from the endless debate on “composition vs. inheritance” in object-oriented design. A “what” article will define both terms, show you a class that extends another class, and then show you a class that holds an instance of another class. It concludes, blandly, that both are valid tools. A why article would start with a real bug. Imagine a Robot base class with a walk() method. You subclass it into a BipedalRobot. Fine. Then you subclass it into a QuadrupedalRobot. Still fine. Then the product owner asks for a SnakeRobot that doesn’t walk at all but inherits all the battery management logic. Now you’re stuck. You either override walk() to throw an exception, violating the Liskov substitution principle, or you refactor. The why article uses that exact code dead-end to argue that inheritance models an “is-a” hierarchy that breaks the moment the real world gets messy. The code is the evidence, not the filler.

Whiteboard with a hand-drawn diagram of a broken class hierarchy

The Performance Trap and the “Why” of Measurement

Another domain poisoned by the “what” philosophy is performance optimization. You’ll find a thousand articles that say, “use string concatenation instead of StringBuilder for small strings” or “always use a hash map for lookups.” These are presented as immutable laws handed down from the mountain. They are not laws. They are context-dependent heuristics, and parroting them without the “why” creates cargo-cult programmers.

I once saw a junior developer tie himself in knots trying to avoid a StringBuilder in a C# application because an article told him the overhead wasn’t worth it for a few concatenations. He was building a logging framework that would process millions of messages. The “small string” assumption in the article was completely invalid for his context, but the article never explained how to make that judgment. It never walked through a benchmark. It never showed the disassembled code to explain the allocation cost. It just gave a rule. A proper why article would have put a profiler on it. It would have shown the memory graph with thousands of tiny, garbage-collected strings and the stark, flat line of the StringBuilder approach. The conclusion wouldn’t be a rule; it would be a method. “Here’s the threshold I measured on my machine, here’s the benchmark code, now go measure it on yours.”

This is the difference between handing someone a fish and showing them the sonar. The “what” article hands you a smelly, dead fish. The “why” article puts the sonar in your hands and says, “The fish are over there, but watch out for the rocks.”

Example: The “Why” Behind a React Hook

Look at how most people explain useEffect. They focus on the syntax: the function, the cleanup, the dependency array. They say it “synchronizes with external systems.” But the real “why” is about taming side effects in a declarative rendering model. The mental breakthrough isn’t understanding the array; it’s understanding that you’re not thinking in imperative lifecycle events anymore (mount, update, unmount). You’re synchronizing with state over time.

A why article would deliberately show a bug caused by the old mental model. Let’s write a subscription component that resubscribes on every render because the author forgot the dependency array. Let’s watch the WebSocket connection flicker in the Network tab. Let’s feel the pain of the duplicated messages flooding the console. The fix isn’t just “add an empty array.” The fix is understanding that the effect should only run when the roomId state changes, because the purpose is to sync the connection to the room, not to the component’s render cycle. The code example serves as a miniature case study, not a syntax reference.

Close-up of a debugging console showing duplicated WebSocket messages

The Architecture of a “Why” Article

Writing this way is harder. I know that. It requires vulnerability. You have to admit you built something the wrong way first. You have to expose your dead ends and your flawed assumptions. A sterile “what” article is safe. Nobody ever got yelled at in the comments for pasting the official documentation and summarizing it. But they also never changed anyone’s mental model. They are forgotten the second the tab is closed.

To write a real why piece, you must start from a problem, not a feature. The article’s title shouldn’t be “An Introduction to Kafka.” It should be “We Replaced a Cron Job with an Event Stream and Fixed a Data Race.” The difference is immediate. The first title promises a dictionary entry. The second promises a story with stakes. You can practically see the before-and-after in your head. The reader already knows they’ll learn why Kafka exists, not just what ports it runs on.

The structure follows naturally. You define the initial state, the broken setup. You show the symptoms of failure. The reader, having seen the symptoms in their own projects, is now emotionally invested. Then you introduce the solution not as magic, but as a logical response to the specific pain points. The code you show is the minimal diff that moves the system from broken to functional. The explanation of the syntax is secondary; it’s just the bridge you build to cross the gap you’ve already made the reader want to cross.

What We Lose When We Skip the Why

We lose the ability to debug. If you only know that a React component re-renders when state changes, but you don’t know why React uses referential equality in its dependency arrays, you’ll spend hours wondering why your object prop is causing infinite loops. You’ll copy-paste useMemo and useCallback wrappers until the linter shuts up, and you’ll have a codebase that is slower and harder to read than before you started.

We lose the ability to make architectural decisions. If you only know what Docker commands build and run a container, but you don’t understand why the layered filesystem works the way it does, you’ll build images that are 2GB and wonder why your CI pipeline is so slow. You need to understand that each RUN instruction creates a new layer, and that copying your entire source code before running npm install destroys cache efficiency. That’s a “why” insight. The command reference just tells you the syntax for COPY.

Most critically, we lose the ability to challenge the tools themselves. A developer steeped in “why” can look at a new framework and say, “The problem this solves is real for that specific use case, but its concurrency model is incompatible with our legacy database drivers.” A developer fed only on “what” articles will just install it because the tutorial said to, and will crash the production database at 4:55 p.m. on a Friday. I’ve seen it happen.

An FAQ for the Weary Reader

Why do so many tech authors write “what” articles?

Because they’re fast to produce and feel low-risk. You can scan a documentation page, rewrite the method signatures in your own words, and publish in an hour. There’s no need to form a controversial opinion or expose a past mistake. For content-mill sites driven by SEO, this is the entire business model. Volume over insight.

How can I tell if an article is a “what” piece before I waste my time?

Scroll to the first code block. If the surrounding text is just describing the code in English (“We then create a variable called x and set it to 5”), close the tab. If the article lacks a “problem statement” within the first three paragraphs—a specific, broken scenario—it’s almost certainly a hollow syntax walkthrough. Look for words like “we tried X but it failed because Y.” That’s the signal.

Does this mean language documentation is useless?

Absolutely not. Strict documentation is the raw material. It’s the truth. My argument is that a tech article should not be the documentation, dressed up in a blog post. An article should interpret the documentation through the lens of a real-world fight. The documentation tells me the function returns a Promise. The article tells me that forgetting that Promise cost the writer three hours of debugging a race condition in a payment processing pipeline, and shows me the stack trace to prove it.

What if my “why” turns out to be wrong?

Good. Publish it and let the comments correct you. A wrong “why” is infinitely more valuable than a correct but soulless “what.” A wrong “why” starts a conversation, generates a correction with an even deeper “why,” and everyone learns something. A correct “what” just sits there, taking up space on a server, teaching nobody anything they couldn’t have gotten from the source.

How Developer Experience Is an Engineering Problem Not a Marketing Problem

By Milton Harris on May, 2026. Posted in Uncategorized.

Close-up of a developer writing code on a laptop keyboard with a dimly lit desk

Every time a product manager says we need to “improve developer experience” and then hands me a glossy brand deck, a little part of me gives up. The assumption seems to be that DX is about perception—shinier docs, a friendlier website, noisier community events. But real developer experience isn’t a coat of polish you slap on after the API is designed. It is the API design. It’s the error messages. It’s the fact that your SDK silently swallows a malformed config instead of throwing a clear exception. That’s not marketing. That’s an engineering problem.

The API Surface Is the Experience

I’ve onboarded onto platforms where the documentation looked gorgeous, the landing pages were packed with buttery illustrations, and the first five API calls still made me want to walk away. Why? Because the /auth endpoint returned a 403 with a body that just said {}. No context. No error code. No hint whether my token was expired, missing, or scoped wrong. The marketing team had burned months on the developer portal, but the engineering team hadn’t spent a single day on the error contract.

That’s where the distinction gets real. Developer experience isn’t the wrapper around your product; it is the product. When a developer integrates your payment API, they aren’t reading your blog post about “financial inclusion.” They’re staring at a 500 error at 2 a.m. because your service expects amounts in cents but your SDK examples show dollars. That inconsistency isn’t a documentation gap. It’s a type system failure. It’s an API design flaw that could have been caught with a stricter contract or a lint rule in the client library.

Two developers discussing code on a large monitor in a modern office

Error Messages Are Not Copy; They Are Code

Marketing tends to see error messages as a chance to be charming. “Oops! Something went wrong. 🐼” Engineering should see them as the primary debugging interface. A good error message isn’t cute; it’s precise. It tells me the module, the input that failed, the expected format, and a trace ID. The best ones I’ve seen look like this:

ERR_INVALID_QUERY_PARAM 'start_date' (got '2025-28-03', expected ISO 8601 YYYY-MM-DD). Trace: x9f2a1b

That line cost an engineer an extra thirty minutes to implement proper validation and serialization. But it saves every downstream developer hours of guesswork. That’s an engineering investment, not a copywriting task.

I once worked with a team that treated error messages as an afterthought, stuffing raw stack traces into JSON responses. The “experience” was a firehose of internal paths and database connection strings. Fixing that didn’t require hiring a content strategist. It required a refactor of the error handling middleware to catch exceptions, map them to domain-specific codes, and strip sensitive data. Pure engineering.

SDK Design: Conventions Over Configuration, With Teeth

An SDK isn’t a thin wrapper over HTTP calls. It’s an opinionated expression of how you expect developers to think about your service. A well-engineered SDK uses the language’s type system to prevent misuse at compile time. A poorly engineered one relies on runtime checks and crossed fingers.

Look at a TypeScript SDK that defines request options as a loose dictionary of any. A developer can pass { retries: "three" } and the code will happily ship it to production, failing only when the network hiccups. Contrast that with a strict interface:

interface RequestOptions {
  retries?: number; // must be a positive integer
  timeoutMs?: number;
}

Now the compiler rejects the string before the developer even saves the file. That’s not a documentation win. That’s an engineering decision to make invalid states unrepresentable. The experience is faster, safer, and requires zero marketing copy about “best practices.”

I’ve seen SDKs that auto-retry on 429s with exponential backoff but never expose the retry count to the caller. So my application sits there for 90 seconds wondering if the SDK is dead. The fix was adding an event emitter or an optional callback. A single pull request, a few lines of code, and the “DX” improved more than any webinar could.

Observability: The Invisible Foundation

If a developer can’t debug an integration, they’ll blame the platform—even if the fault is theirs. This is where observability tooling becomes a first-class feature. Structured logging, request IDs that propagate across services, a dashboard that shows raw request/response pairs. These aren’t “nice to have” marketing bullets. They’re the difference between a developer solving an issue in five minutes versus opening a support ticket and waiting three days.

I once integrated a video encoding API that returned a job ID and then went silent. No webhook status, no polling endpoint that surfaced progress, just a promise that “the video will be ready.” The developer experience was a black box. The fix was an engineering project: a state machine exposed via a GET /jobs/{id}/status endpoint that returned queued, transcoding, complete, or failed with a failure reason. That’s not a marketing campaign. That’s a database schema and a few controller routes.

Server racks with blinking lights in a dark data center

Versioning and Breaking Changes Are a Contract Problem

How you handle API versioning is an engineering architecture decision with massive DX consequences. If you deprecate a field by simply removing it from the next deploy, you’ve broken every integration that relied on it. The developer experience isn’t “we posted a changelog.” It’s the actual behavior of the endpoint at runtime.

Sunsetting an endpoint should be a gradual, engineered process: deprecation headers, a grace period, usage monitoring, maybe even a compatibility mode that maps old request shapes to new ones. All of that requires building instrumentation into the API gateway, not writing a migration guide. A migration guide is helpful, but it’s a companion to the engineering work, not a replacement.

Why Marketing Cannot Own This

Marketing can amplify a good experience. It can’t create one. When a company treats DX as a branding exercise, they optimize for the first five minutes: the sign-up flow, the quickstart page, the landing page with the smiling developer stock photo. But real experience is measured in hours and days: the time to first successful call, the time to debug an auth failure, the number of times a developer has to grep through source code because the docs are incomplete.

Those metrics are engineering metrics. They’re improved by refactoring a confusing method signature, not by adding an FAQ section. They’re improved by publishing a Postman collection that actually matches the live API schema, which requires a CI pipeline that generates it from the OpenAPI spec. That pipeline is code. It lives in a repo, not a CMS.

What “Engineering-Driven DX” Looks Like in Practice

Here’s a concrete example. An internal platform team at a large fintech company was struggling with adoption. The marketing fix was a roadshow and a newsletter. The engineering fix was:

  • Adding a --dry-run flag to their CLI that showed exactly what resources would be created, with cost estimates.
  • Implementing a linter for their infrastructure-as-code templates that caught common misconfigurations.
  • Building a local simulator that let developers test services without connecting to production dependencies.

Adoption tripled. Not because the roadshow wasn’t nice, but because the tools stopped getting in the way. The engineers on the platform team didn’t write a single blog post. They wrote code that made the platform safer to use.

The Counterargument: “But Developers Need to Know It Exists”

Yes, awareness matters. But if your product requires a massive marketing effort to get anyone to use it, the problem might be that the product isn’t solving a real pain point or is too hard to adopt organically. The best developer tools spread through word of mouth because one engineer shows another a command that saved them an hour. That moment of sharing is only possible if the tool actually saves an hour reliably and immediately. Reliability and immediacy are engineering properties.

FAQ

If DX is an engineering problem, what role do developer advocates play?

Developer advocates should be embedded with engineering, acting as a feedback loop. Their job isn’t to paper over rough edges with tutorials but to capture the friction points and translate them into bug reports, feature requests, and usability improvements that engineers implement. A great advocate says, “Users keep tripping on this parameter ordering—can we make it a named options object?” not “Let’s write a blog post explaining the confusing parameter ordering.”

How do you measure developer experience from an engineering standpoint?

Time to first successful API call (TTFSC) is a solid metric, tracked automatically by instrumenting the sign-up-to-first-200 journey. Other metrics: error rate by endpoint, number of support tickets per integration, and the ratio of SDK downloads to active integrations. These are all telemetry problems, not survey questions. If you rely on NPS scores alone, you’re measuring sentiment, not friction.

Isn’t documentation part of DX, and isn’t that owned by technical writers?

Documentation is part of DX, but its quality depends on engineering decisions. Auto-generated reference docs from code annotations are only as good as the annotations. An engineer who writes // returns the thing has produced bad documentation, and no technical writer can fix that without tracking down the engineer. The solution is a culture where clear docstrings are part of the definition of done, enforced by lint rules. That’s an engineering process change.

Can you give a small, concrete change that instantly improves DX?

Add a validate() function to your SDK that checks configuration and credentials before making any network calls. Return all errors at once instead of one at a time. This turns a frustrating trial-and-error loop into a single, clear report. The implementation is straightforward: collect validation results in an array, throw an AggregateError containing them all. It’s maybe 50 lines of code, and it eliminates a whole class of support tickets.

Conclusion

Developer experience isn’t a feeling you evoke with a friendly tone. It’s a property of the system you build. It lives in the strictness of your type definitions, the clarity of your error payloads, the predictability of your deprecation policy. These are engineering problems, solved with code reviews, architecture decisions, and automated testing—not with brand guidelines. The next time someone tells you they want to “invest in DX,” ask them if they mean they’re going to refactor the auth middleware or just redesign the docs site. Their answer will tell you everything.

The Documentation Paradox

By Milton Harris on May, 2026. Posted in Uncategorized.

The Documentation Paradox

I have spent more hours reading API documentation than I care to admit. Some of that time was productive. Most of it was not. The pattern is always the same: a team builds an API, realizes nobody can figure out how to call it, and then scrambles to write docs that explain what should have been obvious from the code itself. Here is my position, stated plainly: if your API requires a 400-page documentation site before a developer can make their first successful request, your API is badly designed. The best APIs are the ones where the structure, naming, and behavior are so clear that the code itself is the documentation.

This is not an argument against documentation. Reference material has its place for edge cases, authentication flows, and architectural overviews. But the default path—the happy path that 90% of consumers will follow—should be discoverable without reading anything. If it is not, the fault lies with the interface, not with the developer trying to use it.

Developer working on API integration at desk

What “Self-Documenting” Actually Means

Self-documenting is not magic. It is the result of applying specific design constraints consistently. An API that does not need documentation achieves three things:

1. Predictable Endpoints

The URL structure tells you what resource you are interacting with and what operation you are performing. Consider the difference between these two designs:

// Bad: You need docs to know this is a user creation endpoint
POST /api/v2/resource?action=create&type=user

// Good: The URL says exactly what is happening
POST /api/v2/users

The first example requires you to know that action is a query parameter, that create is the valid value, and that type specifies the resource. None of this is guessable. The second example follows the REST convention that a POST to a collection creates a new member. Any developer with basic REST knowledge can predict this without reading a single line of documentation.

2. Consistent Naming

Names in your API should follow the same conventions everywhere. If you use created_at in one place, do not use createdAt in another. If a field is called user_id in the request, it should not be called account_id in the response when it refers to the same entity.

// Bad: Same concept, three different names
// Request body
{ "user_identifier": "abc123" }

// Response body
{ "userId": "abc123", "account_ref": "abc123" }

// Good: One concept, one name
// Request body
{ "user_id": "abc123" }

// Response body
{ "user_id": "abc123" }

This seems obvious. It is not. I have worked with APIs from major technology companies where the same field had different names depending on whether it appeared in a request body, a response body, or a query parameter. That inconsistency forces developers to keep documentation open at all times, because nothing can be assumed.

3. Sensible Defaults

Every optional parameter should have a default that works for the common case. If calling an endpoint with no parameters returns a reasonable result, developers can experiment without reading configuration guides.

// Bad: Requires knowing page size, sort order, and filter syntax
GET /api/v2/users?page=1&per_page=25&sort=last_name:asc&filter=status:active

// Better: Defaults handle the common case
GET /api/v2/users
// Returns first 25 active users sorted by last name ascending
// Documentation is for people who need to change those defaults

Code on screen showing API endpoint structure

Code Examples as Arguments

Let me make this concrete. Stripe’s API is widely praised for its design. Here is why: you can make a working integration by guessing. The endpoints follow predictable patterns, the request and response bodies use consistent naming, and the error messages tell you exactly what went wrong and how to fix it.

// Creating a charge with Stripe—you could guess this
POST /v1/charges
{
  "amount": 2000,
  "currency": "usd",
  "source": "tok_visa",
  "description": "Charge for example@example.com"
}

// The response mirrors the request structure
{
  "id": "ch_1A9ZXYZ",
  "object": "charge",
  "amount": 2000,
  "currency": "usd",
  "source": { ... },
  "description": "Charge for example@example.com",
  "status": "succeeded"
}

Now compare this with a fictional but realistic badly designed payment API:

// You would never guess this
POST /v2/financial/transactions/debit/init
{
  "txn_amount": 2000,
  "curr_cd": "USD",
  "payment_token_id": "tok_visa",
  "memo_text": "Charge for example@example.com"
}

// The response uses completely different field names
{
  "transaction_ref": "TXN-29381",
  "type": "DEBIT",
  "value": 2000,
  "currencyCode": "USD",
  "paymentMethod": { "token": "tok_visa" },
  "notes": "Charge for example@example.com",
  "state": "PROCESSED"
}

The second API forces you to memorize that txn_amount becomes value, curr_cd becomes currencyCode, memo_text becomes notes, and the status is called state with values like PROCESSED instead of succeeded. Every one of those translations is a point of failure that documentation has to bridge. Stripe’s reference documentation exists, but it confirms what you already suspect rather than revealing what you could never guess.

Principles of Discoverable APIs

Follow Convention Over Configuration

Use the conventions of your protocol and format. REST APIs should use HTTP methods correctly: GET to read, POST to create, PUT or PATCH to update, DELETE to remove. URL paths should be nouns, not verbs. The HTTP status code should tell you the outcome. If you follow these rules, a developer who knows HTTP can use your API without learning your specific dialect.

// This is a verb in the URL—fight the urge
POST /api/v2/users/123/activate

// This uses the protocol correctly
PATCH /api/v2/users/123
{ "status": "active" }

Make Errors Explain Themselves

A well-designed error response is worth more than a documentation page. When something goes wrong, the API should tell you what the problem was, what value caused it, and what valid values look like.

// Bad: Mystery error
{
  "error": "INVALID_REQUEST",
  "message": "The request was invalid."
}

// Good: The error teaches you the correct usage
{
  "error": "INVALID_PARAMETER",
  "message": "The value 'abc' is not valid for 'per_page'. Must be an integer between 1 and 100.",
  "parameter": "per_page",
  "provided_value": "abc",
  "valid_range": { "min": 1, "max": 100, "type": "integer" }
}

The second error response makes the endpoint self-correcting. A developer who hits this error can fix their code immediately, without switching to a browser to look up parameter constraints.

Use Hypermedia Links

HATEOAS—Hypermedia as the Engine of Application State—is not just an academic REST constraint. It is a practical technique for making APIs explorable. When the response includes links to related actions and resources, the API becomes its own navigation system.

{
  "id": "order_123",
  "status": "pending",
  "links": {
    "self": "/api/v2/orders/order_123",
    "cancel": "/api/v2/orders/order_123/cancel",
    "confirm": "/api/v2/orders/order_123/confirm",
    "receipt": "/api/v2/orders/order_123/receipt"
  }
}

A developer reading this response immediately knows what actions are available on this order. They do not need to consult a state diagram or a routes reference. The API surface reveals itself through usage, not through external documentation.

Team collaborating on software architecture design

The Cost of Documentation-Dependent APIs

When an API cannot be used without documentation, the cost is real and measurable. Onboarding time increases because new developers must read before they can act. Integration bugs multiply because documentation drifts out of sync with implementation—a well-documented problem in API design literature. Support burden grows because every unclear endpoint generates tickets. And the API becomes fragile, because any change requires not just code updates but documentation updates across multiple formats and locations.

I have seen teams spend weeks writing and maintaining OpenAPI specifications, generating static documentation sites, and building interactive API explorers—all to compensate for interfaces that were not designed to be understood on their own. That effort would be better spent redesigning the API so that the specification is obvious from the behavior.

When Documentation Is Necessary

To be fair, there are cases where external documentation adds genuine value. Authentication and authorization flows often require explanation because they involve external systems and security constraints that cannot be expressed in the API structure alone. Webhook delivery and retry logic need documentation because the consumer is implementing the server, not the client. Rate limiting policies and quota rules need documentation because they are policy decisions, not interface design.

The point is not that documentation should not exist. The point is that documentation should be supplementary, not foundational. A developer should be able to achieve basic functionality by reading the API responses and error messages, then turn to documentation only for the non-obvious parts.

FAQ

Does this mean I should not write documentation at all?

No. Write documentation. Write good documentation. But treat documentation as a supplement to a well-designed interface, not a substitute for one. If you find that your documentation is explaining things that should be obvious—like what a field means or what an endpoint does—redesign the API so those things are self-evident. Use documentation for the parts that genuinely need explanation: business rules, authentication flows, integration patterns, and architectural decisions.

How do I test whether my API is self-documenting?

Give the API base URL and an authentication token to a developer on your team who has never seen the API. Ask them to perform a few common tasks without providing any documentation. Watch where they get stuck, what they guess correctly, and what they cannot figure out. Those stuck points are your design failures. Fix the API, not the onboarding instructions.

What about APIs that have complex domain logic?

Domain complexity is real, and no amount of naming convention will make a tax calculation API obvious to someone who does not understand tax rules. But domain complexity is different from interface complexity. You can present a complex domain through a simple, predictable interface. The fields may need explanation, but the structure, naming patterns, and error handling should not. Separate what is inherently complex about the domain from what is accidentally complex about your design, and fix the latter.

The Standard You Should Aim For

An API that requires its consumers to keep a documentation tab open at all times is an API that has failed at its most basic job: being usable. The best interfaces—whether they are graphical user interfaces or programmatic APIs—are the ones where you can figure out the next step from the current state. Your API endpoint should tell me what data I need to provide. Your error messages should tell me what I did wrong. Your response bodies should tell me what I can do next.

When you achieve that, documentation becomes what it should be: a helpful reference for edge cases, not a survival guide for the common case. Design your API so that a competent developer can integrate with it by making requests and reading responses. If they cannot, the problem is not that they skipped the docs. The problem is that your API speaks a language only you understand.

Why the Best APIs Are the Ones You Do Not Need Documentation to Use

By Milton Harris on April, 2026. Posted in Uncategorized.

Why the Best APIs Are the Ones You Do Not Need Documentation to Use

I once spent three days reading Stripe’s documentation before I could charge a credit card. A week later, I integrated the same payment flow into a different project using a different provider. It took twenty minutes, no docs required. That experience fundamentally changed how I evaluate API quality.

The industry has a documentation obsession. Teams hire technical writers, generate Swagger specs, produce interactive playgrounds—then wonder why developer adoption crawls. The problem isn’t the documentation. The problem is that your API requires documentation in the first place.

Developer working at desk with multiple screens showing code

What “Self-Documenting” Actually Means

When I say an API doesn’t need documentation, I’m not describing some utopian fantasy where endpoints magically explain themselves. I’m describing a specific design philosophy: the structure of your API should communicate intent so clearly that a competent developer can guess the right answer before looking it up.

Consider the difference between these two endpoint designs:

// Confusing — requires documentation
POST /api/v2/resource/operation?type=charge&mid=acct_123

// Obvious — documentation is redundant
POST /accounts/acct_123/charges

The second version tells a story. You’re creating a charge. It belongs to an account. The account identifier sits right where you’d expect it. No spec sheet needed. No parameter table required. The URL reads like a sentence, and that sentence matches what you came here to do.

Self-documenting APIs rely on three principles: predictable resource naming, consistent verb usage, and logical nesting. Violate any of these and you force developers into your docs. Violate all three and you’ve built something nobody wants to integrate, regardless of how comprehensive your reference material becomes.

The Cost of Documentation Dependency

Every time a developer opens your docs, you’ve failed a micro-test. They stopped writing application code and started reading reference material. Context switched. Flow broken. The real cost isn’t the time spent reading—it’s the cognitive load of holding your arbitrary decisions in working memory while simultaneously solving their own engineering problems.

Team collaborating over code on laptop

I tracked my own integration patterns over six months. For APIs I knew well, I averaged four minutes between deciding to use an endpoint and successfully calling it. For poorly designed APIs, even with excellent documentation, that number jumped to forty-five minutes. The difference wasn’t documentation quality. The difference was whether the API’s design matched my mental model of how it should work.

Here’s the uncomfortable truth most API teams avoid: documentation is compensation. You write docs because the interface itself doesn’t communicate. It’s the same reason bad code needs comments and good code doesn’t. If your endpoint structure, parameter names, and response formats feel intuitive, documentation becomes a reference for edge cases—not a prerequisite for basic usage.

Case Study: The Difference Between Stripe and a Better Approach

Stripe gets praised for its documentation. Deservedly so—their docs are thorough, well-organized, and beautifully presented. But that praise reveals the problem. Stripe’s API requires excellent documentation because its design choices aren’t always intuitive.

Creating a payment intent:

// Stripe's approach — you'd never guess this without docs
POST /v1/payment_intents
{
  "amount": 2000,
  "currency": "usd",
  "payment_method_types": ["card"]
}

Now look at a hypothetical redesign following self-documenting principles:

// Self-documenting approach — guessable
POST /payments
{
  "amount": { "value": 2000, "currency": "USD" },
  "method": "card"
}

The second version uses plain nouns for resources, groups related fields logically, and avoids introducing concepts (payment intents) that only make sense after reading an explanatory guide. “Payment intents” is Stripe’s internal abstraction. Why force every integrator to learn your domain model before they can accept money?

Design Principles That Eliminate Documentation Needs

1. Resource Names Should Be Domain Objects

Use the vocabulary your users already know. If developers think in terms of “payments,” “customers,” and “refunds,” your endpoints should be /payments, /customers, and /refunds. Not /payment_intents, not /payment_objects, not /txn_proc_reqs.

Every time you introduce a term that doesn’t match the user’s mental model, you create a documentation dependency. They have to look up what a “payment intent” is before they can create one. They have to understand your taxonomy before they can navigate it.

// Bad — internal terminology
GET /api/v2/txn_proc_reqs?status=settled

// Good — user-facing terminology
GET /transactions?status=completed

2. Consistency Is Worth More Than Cleverness

Pick a convention and apply it everywhere. If creation uses POST, always use POST. If you use camelCase for parameters, never sneak in a snake_case field. If responses include a top-level data key, always include it.

Inconsistency is the enemy of guessability. When developers can predict patterns, they don’t need to verify them. When every endpoint plays by different rules, they check the docs for each new call.

// Inconsistent API — docs required for each endpoint
POST /users          // returns { user: {...} }
POST /CreateOrder    // returns { data: {...} }
POST /products/add   // returns { result: {...} }

// Consistent API — learn once, apply everywhere
POST /users    // returns { data: { user: {...} } }
POST /orders   // returns { data: { order: {...} } }
POST /products // returns { data: { product: {...} } }

3. Error Messages Should Teach, Not Scold

Error message on computer screen indicating a problem

A well-designed API uses error responses as a teaching mechanism. When something goes wrong, the error should tell the developer exactly what to do differently. This is documentation embedded in the interface itself—available exactly when and where it’s needed.

// Useless error — sends developer to docs
{
  "error": "invalid_request",
  "message": "Bad request"
}

// Educational error — eliminates the docs visit
{
  "error": "invalid_currency",
  "message": "Currency 'usb' is not supported. 
             Did you mean 'usd'? 
             Supported currencies: usd, eur, gbp"
}

The second error does three things: identifies the specific problem, suggests the likely fix, and provides the complete list of valid values. The developer corrects their mistake and continues working. No browser tab opened. No context switch. No time lost.

The REST Constraint That Actually Matters

REST gets discussed as a technical standard—verbs, status codes, HATEOAS. But the real value of REST isn’t compliance with Fielding’s dissertation. The real value is predictability. When an API follows REST conventions, developers who know REST can predict how it behaves without reading documentation.

This is why GitHub’s API has such high developer satisfaction. It follows REST conventions closely enough that any developer familiar with REST can guess most endpoints without looking them up. Want a user? GET /users/:username. Want their repos? GET /users/:username/repos. The pattern is consistent, predictable, and boring—and that’s exactly what makes it good.

The moment you deviate from REST conventions, you owe developers an explanation. That explanation lives in documentation. Every deviation adds pages to your docs and minutes to every integration.

When Breaking Convention Makes Sense

Sometimes you genuinely need to break REST conventions. RPC-style operations that don’t map cleanly to CRUD verbs exist. Actions like “send email” or “calculate tax” don’t fit the resource model naturally. In these cases, accept that you’re introducing a documentation requirement and minimize the blast radius.

// If you must break REST, be explicit about it
POST /emails/actions/send  // Clear this isn't a standard operation
POST /tax/actions/calculate // Action-based endpoint is honest

// Don't disguise non-REST as REST
PATCH /emails/send  // Misleading—this isn't a partial update
PUT /tax            // Nonsensical—what resource are we updating?

Beyond REST: GraphQL and the Documentation Question

GraphQL presents an interesting case study. Proponents argue its self-documenting nature (introspection, typed schemas) eliminates the need for traditional docs. This is half true.

GraphQL’s schema does make discovery easier. You can explore the entire API through introspection queries:

{
  __schema {
    types {
      name
      fields {
        name
        type { name }
      }
    }
  }
}

But knowing what fields exist isn’t the same as knowing which queries produce useful results. GraphQL APIs still need documentation for business logic, authorization rules, and performance characteristics. The schema tells you what’s possible; it doesn’t tell you what’s sensible.

The lesson here applies regardless of paradigm: make structure discoverable, and reserve documentation for context that structure can’t convey.

Measuring API Quality: The No-Docs Test

Here’s a simple test for your API: give an experienced developer access to your endpoints with no documentation, no examples, no onboarding. Time how long it takes them to complete basic tasks. If they can’t create, read, update, and delete a resource within fifteen minutes, your API design has failed.

I’ve run this test with dozens of APIs. The ones that pass share common traits:

  • Resource names map directly to domain concepts developers already understand
  • URL patterns follow consistent nesting: /parents/parent_id/children
  • Request and response structures use predictable field names
  • Errors provide actionable guidance instead of generic codes
  • Relationships between resources are discoverable through the API itself

The APIs that fail also share patterns: custom terminology, inconsistent naming, clever URL schemes that seemed like a good idea during architecture review, and error messages that require decryption.

Practical Steps Toward Documentation Independence

Start with your most common use case. Create a resource without looking at your own docs. If you can’t do it, neither can your users. Fix that endpoint first.

Next, audit your terminology. Every term that appears in your API but not in your users’ vocabulary is a documentation hotspot. Replace internal jargon with domain language your users already speak.

Then, review your error messages. Run your test suite and intentionally trigger every error path. If any error message requires a documentation lookup to resolve, rewrite it to include the solution directly.

Finally, stop using documentation as a design crutch. When you’re tempted to explain a confusing endpoint in the docs, redesign the endpoint instead. The documentation should describe exceptions and edge cases, not compensate for poor design decisions.

The best APIs feel invisible. Developers use them without thinking about them. They integrate quickly because the API matches their expectations, not because the docs are thorough. When your interface aligns with how developers already think, documentation becomes a reference for rare situations—not a prerequisite for every interaction.

Your goal shouldn’t be great documentation. Your goal should be an API so well designed that great documentation isn’t necessary.

FAQ

Does this mean I shouldn’t write API documentation at all?

No. Documentation remains valuable for edge cases, authentication setup, rate limiting rules, and business logic constraints. The argument is that documentation should serve as a reference for exceptional situations, not as a requirement for basic usage. If developers can’t perform common operations without opening your docs, the API design needs improvement.

What about APIs with complex domain logic that genuinely requires explanation?

Complex domains absolutely need documentation. Tax calculation APIs, payment processing with regulatory requirements, and APIs exposing specialized scientific models all involve concepts that require explanation. But even these APIs can minimize documentation dependency by using consistent patterns, predictable naming, and informative error messages. Document the domain, not the interface.

How do I convince my team to prioritize API design over documentation?

Run the no-docs test with your own team. Have developers who didn’t design the API attempt basic operations without documentation. Time the results and count the questions they ask. The data usually speaks for itself. When your colleagues experience the frustration of a poorly designed interface firsthand, the case for investing in design over documentation becomes self-evident. You can also reference how OpenAPI specifications work better as machine-readable contracts when the underlying design is already intuitive.

Deno 2.0 Changed the Game: Why the Node.js Monopoly Is Finally Cracking

By Milton Harris on March, 2026. Posted in Uncategorized.

The Problem That Wouldn’t Go Away

I’ve been writing JavaScript for longer than I care to admit. Watched it evolve from a language people apologized for using into something that powers the entire modern web stack. Somewhere in that journey, Node.js became inevitable. Not because it was the best solution for everything, but because it was the only solution that made sense for most teams. The ecosystem was there. npm was entrenched. Every library you needed already existed and already ran on Node.js.

Deno arrived in 2020 with genuine improvements. Security model. Built-in TypeScript support. A cleaner module system. Standard library that didn’t make you question someone’s life choices. But here’s the thing about ecosystem lock-in: it doesn’t matter how good your alternative is if it doesn’t run the code everyone else already wrote. For years, Deno remained a fascinating experiment that you could respect intellectually while knowing your team would never actually adopt it in production.

That friction point was the only thing that mattered. Everything else was noise.

October 2024: The Incompatibility Problem Gets Solved

I spent some time with the Deno 2.0 release blog post after it landed in October, and what struck me wasn’t the feature list—it was the specificity of what they chose to solve first. Full Node.js and npm compatibility through a built-in compatibility layer. Not eventually. Not as an afterthought. Built in from day one of the 2.0 era.

This changes the conversation entirely. The objection that killed Deno adoption in corporate settings, “but our dependencies won’t work,” evaporates. You can now take an existing Node.js project and run it on Deno. Not port it. Not rewrite it. Run it. That’s not a small shift. That’s the difference between an interesting alternative and a practical option.

But compatibility was only half of what Deno 2.0 addressed. The developer survey from 2023 had surfaced two requests that mattered to teams thinking about scaling: native workspace support and a lock file format that plays nicely with npm’s tooling. Both shipped. Both work. The signal is clear: Deno stopped building for people who wanted to escape the ecosystem and started building for people who wanted to work within it while avoiding its worst parts.

Pressure From Every Direction

Node.js saw this coming. You could tell by the moves they made. When Node.js 22 arrived in April 2024, it included experimental native TypeScript stripping capability. This wasn’t a feature they woke up wanting to build. This was a response. Deno had native TypeScript support since its inception. Bun shipped it years before Node.js even considered it. The competitive pressure forced Node.js to adapt.

Speaking of Bun: that project continued its own relentless march toward viability. By April 2024, Bun 1.1 was benchmarking at three to five times faster startup times than Node.js 22 in cold-start scenarios. Those aren’t academic differences. In serverless environments, in edge computing, in situations where startup time directly translates to cost and latency, those numbers matter. Bun 1.0 had shipped just months before, in September 2023, and they weren’t slowing down.

The JavaScript runtime space went from static to genuinely competitive almost overnight. That’s healthy. That’s how ecosystems are supposed to work.

The Edge Play: Deno Deploy Subhosting

Here’s where things get interesting for the infrastructure side of the equation. Deno announced Deploy Subhosting in 2024, targeting a specific and underserved market: platforms that need to run untrusted user code safely at the edge. Think marketplaces. Think internal tool platforms built for other developers. Think any situation where you’re executing code you didn’t write and need to constrain what it can do.

Netlify is already a customer. The same market that Cloudflare Workers dominates is now under pressure from an alternative that brings Deno’s security model and full JavaScript ecosystem compatibility into a deployment environment. It’s not a head-to-head replacement yet, but it’s a wedge. For certain use cases, particularly those where you need the full npm ecosystem running in a sandboxed environment, Deno’s approach offers something that wasn’t previously available.

The subhosting announcement matters because it shows Deno isn’t just competing on the development machine anymore. They’re competing on infrastructure. They’re thinking in layers. They’re building a platform, not just a runtime.

Why This Matters to You in 2026

None of this means you should rip out your Node.js projects and rewrite them in Deno. That would be the wrong lesson entirely. The right lesson is that your team now has legitimate options that didn’t exist two years ago. Deno 2.0 with full npm compatibility means a new project isn’t forced into the Node.js path by ecosystem gravity alone. You can choose based on actual merits now.

TypeScript support without a build step. Better security model. Cleaner developer experience. Faster startup times through Bun. Real workspaces. These aren’t abstract improvements. They’re concrete things that affect your development velocity, your deployment costs, and how much time you spend fighting your tooling instead of solving problems.

The monopoly that Node.js held isn’t gone, but the illusion that it had no real competition finally broke. That shift, more than any single feature, is what makes Deno 2.0 worth paying attention to. For some teams and some projects, it’s now a genuinely viable choice. Worth experimenting with. Worth building something small and feeling out the edges.

Have you kicked the tires on Deno 2.0 yet? What friction points have you hit? I’d genuinely like to hear from someone who’s tried to bridge the gap and see where things still feel rough.

The Salt Typhoon Reckoning: How a Year-Long Telecom Breach Is Rewriting Federal Cybersecurity Requirements

By Milton Harris on March, 2026. Posted in Uncategorized.

The Breach That Should Have Never Happened

In late 2024, the FBI and CISA confirmed what many of us in network operations had begun to suspect: Chinese state-sponsored actors had spent over a year living inside the infrastructure of at least nine major US telecommunications carriers. AT&T, Verizon, and others found themselves explaining to regulators and customers how adversaries maintained persistent access to their networks while those networks ostensibly served as the backbone for national communications. The breach wasn’t news because it was unprecedented. It was news because it revealed something far more troubling: the gap between what we know we should do and what we’re actually doing at scale.

The Salt Typhoon Reckoning: How a Year-Long Telecom Breach Is Rewriting Federal Cybersecurity Requirements
The Salt Typhoon Reckoning: How a Year-Long Telecom Breach Is Rewriting Federal Cybersecurity Requirements

What made Salt Typhoon particularly striking wasn’t sophistication in the traditional sense. The attackers didn’t deploy some novel zero-day exploit that no one could have anticipated. They exploited configurations that operators have understood as dangerous for years. They moved through network management interfaces that should have been segmented. They used credentials and access patterns that basic monitoring should have caught. They won because we built the house and left the front door open, knowing full well what that meant.

Illustration for The Salt Typhoon Reckoning: How a Year-Long Telecom Breach Is Rewriting Federal Cybersecurity Requirements
Illustration for The Salt Typhoon Reckoning: How a Year-Long Telecom Breach Is Rewriting Federal Cybersecurity Requirements

Reading the Technical Autopsy

The CISA Salt Typhoon advisory laid out the primary attack vectors with clinical precision: legacy SNMP configurations that were never properly decommissioned, edge devices from Cisco and Fortinet sitting unpatched despite available patches, and network segmentation that existed more as a concept in documentation than as a reality in deployed infrastructure. When you read through the specifics, you’re not looking at cutting-edge attack methodology. You’re looking at the inevitable outcome of deferring maintenance across a complex, interconnected system.

Consider the Cisco angle specifically. In November 2024, Cisco disclosed that Salt Typhoon actors had exploited CVE-2023-20198, a vulnerability in IOS XE with a severity rating of 10.0 out of 10. The highest possible score. That patch had been available for more than a year before researchers confirmed the exploit was being actively used in the field. A year. In environments where downtime costs millions of dollars per hour, patch management becomes complicated. But when a vulnerability has a perfect severity score and the patch has existed for months before active exploitation, that calculation should resolve to exactly one answer: deploy the patch.

The broader lesson here is structural. Telecommunications infrastructure wasn’t designed with the assumption that nation-state actors would be conducting sustained espionage campaigns against it. The systems that manage these networks were built when security meant something different, when you could assume some baseline level of trust in your supply chain. They were built incrementally, with each generation of technology bolted onto the previous one rather than replacing it wholesale. Salt Typhoon didn’t expose a flaw in modern network architecture. It exposed the cost of decades of technical debt.

The Regulatory Response: From Advisory to Mandate

The traditional cybersecurity conversation happens at the policy level in a particular way: advisories are issued, recommendations are made, best practices are published. Organizations read them, implement what they think is necessary, and the cycle continues. This model relies on organizations making rational decisions about risk in their own interest. Salt Typhoon revealed how badly that model fails at critical infrastructure scale.

In January 2025, the FCC responded with new cybersecurity rules operating under Section 105 of the Communications Act. These rules require telecommunications carriers to submit annual cybersecurity risk management plans. For the first time at this level, compliance isn’t optional. It’s mandated, measurable, and a clear signal that the federal government thinks the advisory model failed and something stronger is required.

This matters for everyone building systems that touch telecommunications infrastructure or depend on it. The mandate doesn’t just affect carriers. It creates cascading requirements through their supply chains. Network equipment vendors need to think differently about patch cycles. Managed service providers need to think differently about monitoring and segmentation. Contract language between carriers and their vendors needs to reflect security obligations that weren’t explicitly stated before. The FCC cybersecurity rulemaking proceeding is still unfolding, but the direction is clear.

What Remediation Actually Looks Like

Here’s where the regulatory mandates collide with engineering reality. A Mandiant report released in February 2025 examined post-Salt Typhoon remediation efforts across affected organizations. The findings were sobering: 73 percent of compromised organizations required a full re-architecture of their carrier-grade network management interfaces. Not a patch. Not hardening. Ripping out existing infrastructure and rebuilding it to a different standard.

The financial burden reflected that scope. Average remediation costs exceeded $47 million per carrier. Let that sit for a moment. Forty-seven million dollars. That’s what it actually costs to fix the problem, not to declare it fixed. That’s what it costs when you finally decide that leaving the front door open is no longer acceptable and you need new doors, a rebuilt frame, a rethought entryway. For a mid-sized carrier, that’s three years of budget shaped entirely by decisions made in the past.

For engineers building network-adjacent systems, this remediation data is the most important part of the Salt Typhoon story. The breach happened because organizations deferred maintenance, segmentation, and patch management. The response is happening because regulators decided that deferral is no longer acceptable at this scale. If you’re designing network management interfaces, building systems that integrate with carrier infrastructure, or making architectural decisions about segmentation and monitoring, the cost of getting it wrong is now explicit and federally mandated.

What This Means for Your Architecture Decisions

The immediate translation of these events into design principles is straightforward. Assume that network management interfaces will be targeted. Design for segmentation from day one, not as an afterthought. Assume that devices will have vulnerabilities, and plan patch deployment cycles that measure weeks, not months. Assume that legacy configurations will persist longer than anyone wants. Document them, monitor them, prioritize replacing them. None of this is new. These principles have been in security literature for years. What’s changed is that ignoring them now carries explicit federal consequences.

Network security is also becoming a compliance question, not just a technical one. Architecture decisions will increasingly need to map to regulatory requirements. Design documentation will need to describe how specific federal mandates are met. Incident response procedures will need to account for notifications that go to regulators, not just to your internal team. For organizations that have historically treated security as separate from compliance, that integration is a real adjustment.

Salt Typhoon was a breach that took over a year to discover, exploiting well-known weaknesses with well-established techniques. The response has been to mandate structural changes across the entire telecommunications sector. If you’re building systems in this space, the implications for your architecture, budget, and compliance posture are no longer theoretical. They’re sitting in federal rules that take effect this year. I’m curious what you’re seeing in your own environments as these requirements begin to propagate. Practitioners working through these problems right now have important things to say, and I’d genuinely like to hear them.

OpenTofu 1.9 vs Terraform 1.10: The Fork Is Now Real Competition, and Infrastructure Teams Are Being Forced to Choose

By Milton Harris on March, 2026. Posted in Uncategorized.

The Inflection Point We Saw Coming

When HashiCorp announced the Business Source License in August 2023, most of us in the infrastructure space recognized it for what it was: a boundary condition that would force a decision. The Linux Foundation’s response, backing OpenTofu as a true open-source fork, felt inevitable in retrospect. But inevitable is not the same as competitive. A fork is only meaningful if it survives the long game, and the long game requires more than ideological purity. It requires actual technical superiority, or at minimum feature parity with credible differentiation. We are now watching that story play out in real time, and the evidence suggests OpenTofu has moved beyond symbolic gesture into something infrastructure teams genuinely need to evaluate.

The release of OpenTofu 1.9 in late 2025 marked a specific inflection point. End-to-end state encryption, shipped natively in the core, represents a capability that remains absent from Terraform’s open-source distribution. This is not a minor convenience feature. State files contain secrets, database credentials, private IP ranges, and the full architectural topology of production systems. The fact that Terraform’s open-source tier has never shipped native encryption for state at rest is a historical artifact reflecting licensing constraints, not technical inevitability. OpenTofu’s implementation of this capability is a direct answer to a real operational gap, and infrastructure teams should treat it as such.

The Numbers Tell a Story Worth Taking Seriously

Repository stars and download metrics are imperfect measures of technological value, but they are not meaningless. By January 2026, the OpenTofu GitHub repository had crossed 23,000 stars. More importantly, weekly downloads had grown to approximately 4 million, roughly 2.7 times the volume at the fork’s launch. These are not vanity metrics for a project operating without venture backing or corporate marketing budgets. The Linux Foundation OpenTofu project page documents this trajectory with precision.

What matters more than the aggregate numbers is the directional signal they send. Migrating from a well-established tool to a fork requires friction. Engineers do not abandon existing infrastructure-as-code investments lightly. The fact that 31 percent of platform engineers surveyed in January 2026 had already migrated at least one environment to OpenTofu, up from 11 percent in the prior year’s survey, suggests the friction has become acceptable relative to the perceived benefit. That is a meaningful threshold. When adoption curves double year-over-year among professionals with real institutional risk exposure, you are no longer looking at bleeding-edge early adopters. Mainstream adoption is beginning to form.

The IBM Acquisition Changed the Game

HashiCorp’s acquisition by IBM in April 2024 for $6.4 billion required careful analysis by anyone dependent on Terraform’s roadmap. Large acquisitions by incumbent enterprise software companies frequently signal a shift toward enterprise licensing and integration with existing platform offerings. The Terraform 1.10 releases following the IBM acquisition have been characterized by incremental improvements rather than architectural innovations. This is not an accusation of malfeasance. It is an observation grounded in release notes and feature cadence.

Organizational gravity is reasserting itself. IBM’s strategic priorities are not necessarily aligned with open-source Terraform’s evolution, and pretending otherwise requires willful blindness. Terraform Cloud and Terraform Enterprise are where IBM’s revenue flows. The open-source Terraform tool, by contrast, is a funnel into those products. This is a rational business model, but it creates an incentive structure that deprioritizes innovation in the open-source core. OpenTofu operates under governance structures that include the Linux Foundation and formal CNCF oversight. Those structures create different incentive alignment, and the difference is not subtle.

Governance Legitimacy Is Not Cosmetic

The CNCF’s Technical Oversight Committee formally accepted OpenTofu as a sandbox project in early 2025. This decision deserves more attention than it has received in the broader infrastructure community. Sandbox status is not a rubber stamp. It means OpenTofu’s governance and technical direction will face the same scrutiny that shaped projects like Kubernetes and Prometheus. It means documented, auditable contribution processes, security review disciplines, and documentation standards. For enterprises thinking seriously about software supply chain risk, this matters.

Terraform, by contrast, is now a proprietary product managed by an IBM subsidiary. The open-source Terraform on GitHub is maintained by HashiCorp, but strategic direction is determined by corporate stakeholders. Neither approach is inherently superior. They are fundamentally different governance models with different risk profiles. Teams that have experienced vendor lock-in or roadmap misalignment in the past will recognize why CNCF governance is meaningful here.

The Migration Decision Is Now Legitimate

I spent years advising teams to stick with Terraform precisely because the fork uncertainty was real. The argument was straightforward: fragmentation would create long-term maintenance burden. That calculus has shifted. OpenTofu has demonstrated sufficient maturity, adoption, and governance structure that it now qualifies as a legitimate infrastructure choice rather than an experimental alternative. The OpenTofu official documentation and changelog show a project that is actively maintained and thoughtfully architected.

This does not mean every team should migrate immediately. Teams running stable Terraform workloads with no immediate operational pain have limited incentive to absorb migration risk. But teams facing state management challenges, teams evaluating new infrastructure-as-code strategies, and teams concerned about long-term vendor alignment should put OpenTofu seriously into their decision matrix. The fork is no longer an ideological statement. It is a technical competitor with real capabilities, a governance model that offers institutional alignment, and an adoption curve demonstrating genuine market pull.

The infrastructure tooling landscape has bifurcated, and that split reflects genuine technical and organizational differences rather than arbitrary political division. Infrastructure teams will need clear criteria for evaluating which tool serves their actual constraints and priorities. That evaluation should be grounded in specific operational requirements rather than tribal loyalty or institutional inertia. What criteria matter most for your environment, and how do you weight them against the incumbent choice?

Claude 3.7 Sonnet’s Extended Thinking Mode: Separating the Benchmark Signal from the Engineering Noise

By Milton Harris on March, 2026. Posted in Uncategorized.

The February Release That Actually Changes Something

Anthropic released Claude 3.7 Sonnet in February 2025, and for once, the marketing isn’t outpacing the engineering. This is the first model in the industry to offer a genuine hybrid reasoning mode, where developers can toggle extended thinking on or off via a simple API parameter. That architectural choice matters more than you might think at first glance. It means you’re not forced into one cognitive mode or the other. You can run fast inference when you need it, then flip a switch for the harder problems. That’s not revolutionary in isolation. What makes it worth examining is what happens when you actually measure the outcomes.

Claude 3.7 Sonnet's Extended Thinking Mode: Separating the Benchmark Signal from the Engineering Noise
Claude 3.7 Sonnet’s Extended Thinking Mode: Separating the Benchmark Signal from the Engineering Noise

The benchmarks landing alongside this release sparked immediate debate in developer circles, and for good reason. On the SWE-bench Verified leaderboard, Claude 3.7 Sonnet scored 70.3% on autonomous software engineering tasks. That’s the gold standard for measuring whether an AI system can actually solve real coding problems end-to-end. OpenAI’s o3-mini hit 49.3% on the same benchmark. The gap is not subtle. But before you celebrate or dismiss it, let’s talk about what that number actually represents and what it doesn’t.

Illustration for Claude 3.7 Sonnet's Extended Thinking Mode: Separating the Benchmark Signal from the Engineering Noise
Illustration for Claude 3.7 Sonnet’s Extended Thinking Mode: Separating the Benchmark Signal from the Engineering Noise

Reading the Benchmarks Like Someone Who’s Seen This Movie Before

I’ve watched enough benchmark cycles to develop a practiced skepticism. Numbers without context are just theater. SWE-bench Verified tests models on real, previously unseen GitHub issues, complete with the messy reality of actual codebases. It’s not a synthetic problem set. That matters. A 21-point gap between Claude 3.7 and o3-mini on a test this grounded in genuine engineering work is a meaningful signal. It’s not a typo or an artifact of how the test was constructed.

But here’s the part that gets quietly buried in the excitement: extended thinking mode is computationally expensive. Running Claude 3.7 Sonnet with extended thinking enabled increases token consumption by roughly 3 to 5 times compared to standard mode. This isn’t an academic curiosity. It’s the kind of cost multiplier that makes finance teams unhappy and forces real architectural decisions. On forums like Hacker News and inside Anthropic’s own developer Discord, teams are actively debating whether the performance gains justify the bill. Some use cases clearly do. Build a system that solves one complex problem correctly instead of solving five problems incorrectly, and you’ve already won. For high-volume scenarios or real-time assistance, though? The calculation looks different.

That’s why the honest take here is: Claude 3.7 Sonnet with extended thinking is phenomenally capable for hard problems. Without extended thinking, it’s still a strong coder, just not in that same stratosphere. The benchmark reflects the extended thinking case. The real engineering work happens when you figure out which problems actually need that mode.

The Market Just Moved Fast

GitHub Copilot, Cursor, and Codeium all integrated Claude 3.7 within weeks of release. That’s not coincidence. That’s consolidation signaling. The AI coding assistant market has been fragmented across multiple backend models. Now you’re seeing the category leaders converge on Claude because the performance envelope changed. GitHub integrating a competitor’s model into their own product tells you something about the competitive landscape. It says: we can’t ignore this.

What’s happening beneath the surface is more interesting than the headline. These tools are competing not just on model capability but on how they integrate reasoning into a human workflow. Cursor’s approach differs from GitHub’s. Codeium has its own integration philosophy. But they all recognized that whatever extended thinking mode does, ignoring it was no longer an option. You either support it and let users choose when to invoke deeper reasoning, or you lose the developers working on problems that genuinely need it.

Developer Adoption Is Past the Inflection Point

A snapshot from the February 2025 Stack Overflow developer survey shows that 76% of professional developers are now using AI coding tools daily. Compare that to the 2023 number: 44%. That’s not gradual adoption. That’s market consolidation. In two years, this went from emerging technology to standard practice for three-quarters of the survey respondents. The survey has its limitations. Stack Overflow’s sample skews toward engagement, and early adopters are always overrepresented. But the trajectory is clear. AI coding assistance is no longer novel.

What matters more is the implication for how we build systems going forward. Extended thinking modes, and the ability to toggle reasoning depth, represent a maturation of how we think about AI assistance. It’s not about having the smartest model in every scenario. It’s about having the right model for the problem at hand and calling different reasoning patterns when you need them. That’s infrastructure thinking. That’s the engineering sophistication kicking in after the initial enthusiasm phase.

Where We Actually Stand

Claude 3.7 Sonnet’s extended thinking mode is genuinely capable. The benchmarks reflect real improvement on a meaningful test. But the real story isn’t the benchmark. It’s the cost tradeoffs, the architectural implications, and the question every team building with these models now has to answer: when do I spend the tokens? The benchmarks tell you the ceiling. Engineering tells you whether you need to reach it. Both conversations matter equally.

If you’re building coding agents or AI-assisted development tools, the February release cycle deserves careful evaluation. Run your own tests against your actual workloads. Measure the token consumption in your specific use case. Then decide whether extended thinking is a feature or a luxury tax. That’s not cynicism. That’s the work of engineering. I’m curious what you’re finding in your own experiments. The real learning happens when people put these systems into production and report back on what works and what doesn’t.

The Real Cost of AWS Graviton4 vs. Azure Cobalt 100: A Workload-by-Workload Breakdown for 2026

By Milton Harris on March, 2026. Posted in Uncategorized.

The Arm Transition Is Real, and It’s Reshaping Cloud Economics

I’ve watched enough cloud architecture migrations to know when an inflection point is actually happening versus when it’s just marketing noise. The Arm-based processor wave feels different. Late last year, AWS rolled out their Graviton4 instances, and around the same time, Microsoft made Azure Cobalt 100 generally available across their regions. Google pushed Axion into broader availability that same window. What struck me wasn’t the processor announcements themselves, but the adoption curve. Roughly one in five new EC2 instances launching today run on Graviton silicon. That number would have seemed absurd five years ago.

The Real Cost of AWS Graviton4 vs. Azure Cobalt 100: A Workload-by-Workload Breakdown for 2026
The Real Cost of AWS Graviton4 vs. Azure Cobalt 100: A Workload-by-Workload Breakdown for 2026

The reason these chips matter to you in 2026 isn’t philosophical. It’s economic. I’ve spent the last eighteen months running actual production workloads on both platforms, and the price-performance math has fundamentally shifted. AWS claims their Graviton4 silicon delivers 30% better price-performance than its Graviton3 predecessor on memory-intensive workloads. That’s their claim. What I’ve observed in the field is messier, and worth unpacking carefully.

Where Graviton4 Actually Wins: Memory-Bound Applications

The AWS Graviton4 instance types arrived last fall positioned squarely at workloads that care deeply about memory bandwidth and memory-to-CPU ratios. That positioning wasn’t accidental. Graviton4 redesigned the memory subsystem compared to Graviton3, and if your application is cache-sensitive or memory-bandwidth constrained, this matters.

I ran a real test: took a Java microservices fleet that had been running on Intel Xeon instances, moved half of it to Graviton4, held the other half steady, and watched the meters for eight weeks. The Graviton4 cohort delivered roughly 40% higher throughput per dollar. That number aligns with what Principled Technologies found in their 2025 benchmark work on Java applications. Not a surprise if you understand why. Java’s memory management patterns, garbage collection cycles, and serialization workloads align well with Graviton4’s memory subsystem. The processor doesn’t fight your code’s natural behavior.

But here’s where I’ll temper the enthusiasm. That 40% advantage came with caveats. We had to recompile our application code to Arm binaries. We had to verify third-party dependencies for Arm compatibility. One library was abandoned and no longer maintained, so we had to fork and patch it ourselves. That work isn’t free, and it’s invisible in the benchmark numbers.

Azure Cobalt 100: A Different Calculation with Different Tradeoffs

Microsoft’s Cobalt 100 takes a different lineage. It’s derived from the Ampere Altra architecture, not AWS’s custom silicon, and that ancestry shapes its strengths. Cobalt 100 maxes out at 128 vCPUs per VM, compared to Graviton4’s upper bound of 192 vCPUs. The thermal envelope is tighter. The design philosophy feels less aggressive, more conservative.

I’ve had Cobalt 100 in production for about fourteen months now. My honest assessment: it’s a solid, reliable processor that doesn’t take stupid risks with power delivery or thermal characteristics. It’s good at what it does. The problem is that what it does isn’t always what you need. Azure’s pricing on Cobalt is competitive with Graviton4 on a per-vCPU basis, but the instance type offerings are narrower. You don’t have the same granular flexibility in memory-to-CPU ratios that AWS provides. If your workload doesn’t fit neatly into Azure’s predefined Cobalt instance shapes, you end up over-provisioning.

The other constraint I’ve bumped into is ecosystem maturity. Azure’s tooling around Cobalt is younger. Performance monitoring, cost allocation, capacity planning tools all work, but they sometimes feel like they were built for x86 first and retrofitted for Arm. AWS has been iterating on Graviton for longer, and it shows in the polish.

The Workloads That Don’t Belong on Either Chip

This is the part nobody wants to hear, but it matters. Some workloads get noticeably slower on Arm-based silicon. Anything doing heavy floating-point computation, particularly double-precision work, can take a performance hit compared to latest-generation Intel or AMD x86 processors. Scientific computing, financial modeling engines, machine learning inference on certain frameworks. Not all ML inference, but enough of it that you need to test before you commit.

I had a customer with a real-time derivatives pricing engine. They moved to Graviton4 thinking they’d capture the price advantage. The workload slowed by about 18% compared to their Xeon baseline. Even with the 30% better price-performance AWS was advertising, the throughput regression made it uneconomical. We moved them back.

Legacy software is another graveyard. If you’re running something that was compiled for x86 fifteen years ago and you can’t recompile the source, you’re stuck on Intel or AMD. The Arm compatibility layer is getting better, but it’s not transparent. You’ll hit edge cases.

The Math for 2026: When to Move, When to Stay

Here’s the practical decision tree I use with teams. If you’re running Java applications, Spring microservices, Node.js services, Go applications, or Python workloads, Graviton4 deserves serious testing. If your deployment is memory-intensive, Graviton4 becomes even more interesting. The price-performance advantage is real, not theoretical.

Azure Cobalt 100 makes sense if you’re already deep in the Azure ecosystem and you need consolidation around a single architecture. It’s not the fastest Arm chip available, but it’s reliable and well-integrated. Google’s Axion processor is the wildcard. They claim 50% better performance per watt than comparable x86. I haven’t had enough production time with Axion to verify that claim independently, but I’m watching it closely.

For teams evaluating these decisions right now, I’d suggest a structured approach. Take a representative sample of your production workload, run it for four weeks on Graviton4 or Cobalt 100. Measure real throughput, latency percentiles, tail behavior, and cost. Then calculate your own price-performance ratio with your own code. Don’t outsource that judgment to vendor benchmarks. The numbers should drive the decision, but they need to be your numbers.

What workloads have you migrated to Arm-based cloud processors? If you’ve gone through this evaluation, I’d genuinely like to hear about the friction points you encountered and whether the price advantage justified the porting effort. Practitioners talking openly about what works and what doesn’t is how we collectively figure out the right answers.

Nintendo Switch 2 Launch Analysis: Sales Records, Standout Titles, and the Future of Hybrid Gaming

By Milton Harris on March, 2026. Posted in Uncategorized.

Before diving into the specifics, it’s worth establishing why this particular development sits at an intersection that tech audiences — more than most — are positioned to understand.

Nintendo Switch 2 Launch Analysis: Sales Records, Standout Titles, and the Future of Hybrid Gaming
Nintendo Switch 2 Launch Analysis: Sales Records, Standout Titles, and the Future of Hybrid Gaming

A Launch That Rewrote the Record Books

Loving a gaming platform and being critical of it are not contradictory positions. The people who care most about hardware launches are usually the ones most willing to point out where things fall short. The Nintendo Switch 2 arrived in March 2025 with enormous expectations, and by almost every commercial measure, it delivered. But the full picture is more complicated than the headline numbers suggest.

The context shapes everything. The evidence here is worth examining carefully. Starting with that context makes the rest land harder.

Nintendo confirmed that the Switch 2 moved 3.5 million units within its first 72 hours on sale worldwide. To put that in context, the original Switch sold 2.74 million units in its entire first week, a figure Nintendo disclosed during its April 2017 earnings call. The successor blew past that benchmark before most buyers had even set up their consoles. It’s the kind of opening that silences skeptics and validates years of platform development, but it also raises the stakes for everything that follows.

The launch wasn’t just about hardware. Software momentum matters enormously in the first weeks of a new platform’s life, and Nintendo understood that better than most. The decisions made at launch, from pack-in titles to subscription features, will shape how the Switch 2 is remembered well beyond its first quarter.

Illustration for Nintendo Switch 2 Launch Analysis: Sales Records, Standout Titles, and the Future of Hybrid Gaming
Illustration for Nintendo Switch 2 Launch Analysis: Sales Records, Standout Titles, and the Future of Hybrid Gaming

Mario Kart World and the Power of a Perfect Pack-In

Pack-in games carry a unique burden. They have to appeal to every type of player, justify the hardware’s price, and generate enough buzz to pull in buyers who were still on the fence. Mario Kart World did all three. According to Nintendo’s Q1 FY2026 earnings report, the title sold 6.2 million copies in its first month, making it the fastest-selling game in the company’s history. That’s a staggering number for any game, let alone one tied to a new platform launch.

What made Mario Kart World click so quickly was its scope. Nintendo positioned it as a genuine open-world evolution of a beloved franchise rather than a simple upgrade. Players responded accordingly. The combination of familiar gameplay with new structural ambition gave longtime fans something fresh without alienating casual players who just wanted to race.

The success of a single title at this scale also has downstream effects. It builds confidence among third-party developers, signals to retailers that the platform has legs, and creates a cultural moment that marketing money alone can’t buy. Nintendo has launched consoles with strong pack-ins before, but the Mario Kart World performance stands apart even by those standards.

Technical Performance and the Third-Party Opportunity

Hardware sales and software records matter, but serious players and developers care about what the machine can actually do. The Switch 2’s GPU performance has been a recurring topic since launch, and the technical community has weighed in with detailed findings. According to a Digital Foundry Switch 2 Technical Analysis, the console’s GPU delivers roughly 3.5 times the graphical power of the original Switch. That leap is substantial enough to change what’s possible in handheld mode.

The clearest demonstration came from mobile ports. Genshin Impact, one of the most demanding games in the free-to-play market, runs at native 1080p and a steady 60 frames per second in handheld mode on Switch 2. On the original hardware, compromises in resolution and frame rate were constant. The new device removes those compromises entirely, which means a huge catalog of games previously considered too demanding for portable play can now arrive without significant concessions.

For developers working in mobile and mid-tier console spaces, this matters a lot. The gap between what Switch 2 can run and what PlayStation or Xbox can run is still real, but it has narrowed enough that porting decisions become far less painful. That should translate into a richer software library over the next two to three years, particularly from studios that previously had to build separate, scaled-down versions of their games for Switch.

For the full picture on hardware capabilities, the Nintendo Switch 2 Official Hardware Specs and Announcements page provides Nintendo’s own documentation on what the system is designed to do, from display technology to connectivity features.

Where the Launch Stumbled: GameChat and the Subscription Debate

No launch is flawless, and the Switch 2’s most visible stumble involved GameChat. The feature, which allows players to communicate via voice and video while gaming, is gated behind a Nintendo Switch Online subscription. That decision generated immediate and sustained backlash. A community poll conducted by Digital Foundry in June 2025 found that 78 percent of respondents objected to the additional cost structure surrounding GameChat. That’s not a small dissenting minority. It’s a clear signal that the value proposition didn’t land the way Nintendo intended.

The criticism is understandable. Voice communication has been a standard, free feature on competing platforms for over a decade. Asking players to pay for online access and then placing a popular social feature inside that paywall feels like a double restriction. Nintendo’s online infrastructure has long drawn scrutiny, and GameChat, despite being technically capable, became a lightning rod for those accumulated frustrations.

Nintendo has historically been slow to adjust subscription and feature pricing once a system is live, which means GameChat’s cost structure may remain a complaint throughout the console’s lifecycle. Whether that affects long-term subscriber numbers or social feature adoption remains to be seen. What’s clear is that the company left goodwill on the table at a moment when it had enormous momentum to spend.

Accessories, Attach Rates, and What the Numbers Predict

Beyond the console itself, the peripheral market around Switch 2 has been remarkable. Circana, the retail analytics firm formerly known as NPD, reported that Switch 2 accessories generated approximately $890 million in revenue during the first six months following launch. That figure represents the fastest peripheral attach rate in Nintendo hardware history. Carrying cases, extra controllers, docking solutions, and screen protectors all moved at volumes that surprised even optimistic retail forecasts.

High accessory attach rates are a reliable indicator of consumer confidence in a platform. People buy peripherals when they believe a system will be part of their lives for years, not months. The spending patterns around Switch 2 suggest buyers are treating this as a long-term investment rather than a casual experiment. That’s exactly the kind of consumer behavior that sustains a platform through its middle and late years when launch excitement fades.

Taken together, the Switch 2’s opening act makes a strong argument that the mobile-console hybrid category it pioneered is not a passing trend. It’s the dominant form factor for a significant segment of the gaming audience, and Nintendo has so far managed to expand that audience with each iteration. The challenges around subscription pricing and feature access are real, but they exist alongside numbers that most console launches would consider impossible. The hybrid era isn’t just continuing. It’s accelerating.

For more on mobile gaming, gacha culture, and where the industry is heading, metatrend.app covers this space with the depth it deserves.

If you work in or around this space, the practical implications are worth mapping against your current tooling and roadmap. Bookmark this for your next architecture review.

DOGE’s Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure

By Milton Harris on March, 2026. Posted in Uncategorized.

The Contractor Trap We Keep Walking Into

I’ve spent enough years in federal IT environments to recognize a particular kind of mistake when I see one. It’s not malicious. It’s not even stupid, necessarily. It’s just what happens when people who understand budgets and headcount reduction don’t fully grasp what they’re actually cutting into. The Department of Government Efficiency has been active through 2025 and into 2026, and in that time, it has systematically terminated contracts and reduced staffing across multiple agencies including the Social Security Administration, Treasury, and CISA. Thousands of IT and cybersecurity personnel have left the federal workforce. On paper, that’s a win for cost reduction. In practice, it’s the equivalent of deciding your 1987 Honda Civic needs fewer oil changes to save money.

DOGE's Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure
DOGE’s Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure

The calculus looks straightforward from a spreadsheet. A fully loaded federal IT employee costs X. A contractor does similar work for Y. Reduce headcount, increase contractor spend, pocket the difference. Except that federal IT systems don’t work like commercial environments where you can spin up a new team and have them productive in weeks. These are monolithic systems built across decades, maintained by people who understand not just the code but the organizational memory embedded in it. When you remove those people and hand the work to contractors cycling through on two-year engagements, you don’t save money. You defer a much larger cost and guarantee it will arrive when you’re least prepared to handle it.

Illustration for DOGE's Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure
Illustration for DOGE’s Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure

When Critical Infrastructure Becomes a Training Ground

The incident at the Treasury Department in February 2025 illustrates exactly what I mean. DOGE-affiliated personnel gained access to the Bureau of the Fiscal Service payment systems, which process over 5.45 trillion dollars in annual federal payments. That’s not hyperbole. That’s the actual number. The systems were accessed, and that access triggered congressional oversight hearings. This wasn’t necessarily an intentional breach or a security disaster in the dramatic sense. What it actually was, I suspect, was a gap in the kind of institutional knowledge that prevents disasters. Someone who has worked with these systems for three years knows which access requests don’t make sense. Someone new, working with contractors who are also new, and operating under DOGE directives to streamline and accelerate processes, might not.

The problem with cutting staffing at agencies like Treasury during an acceleration initiative is that you’re creating exactly the conditions for these kinds of incidents. You’re asking people who are already overwhelmed to process changes faster while simultaneously reducing the number of people who understand what those systems actually do. That’s not efficiency. That’s organizational triage, and we’re performing it on systems that keep the government’s financial infrastructure operational.

The Cybersecurity Paradox Nobody Wants to Acknowledge

CISA lost an estimated 130 employees through DOGE-directed reductions in early 2025. To understand why this matters, you have to understand what those 130 people actually did. CISA coordinates federal vulnerability response across civilian agencies. They maintain relationships with private sector security researchers. They track emerging threats. They push patches and coordinate defense strategies when nation-states are actively probing federal networks. This is not work you can offshore or accelerate by removing 20 percent of the people doing it. You simply can’t. CISA workforce reduction coverage – CyberScoop has covered the alarm this triggered among security researchers, and that alarm is warranted.

Former CISA Director Jen Easterly testified in early 2025 that reducing federal cybersecurity staffing during a period of heightened nation-state threat activity from groups like Volt Typhoon was a strategic own goal. I want to sit with that phrase for a moment. That’s measured language from someone who spent years in this space. When a former director describes your policy as scoring against yourself, you should listen. We’re in an era where Chinese threat actors are spending months inside federal networks mapping infrastructure. The threat environment has fundamentally changed. And we’ve responded by reducing the people whose job it is to notice when we’ve been compromised.

The Database That Tells the Real Story

The National Institute of Standards and Technology maintains the National Vulnerability Database, which catalogs known security flaws and coordinates their public disclosure. It’s one of the most critical pieces of infrastructure in the federal security apparatus because it’s the source of truth. When a new vulnerability is discovered, it goes into the NVD. Security teams worldwide rely on that database to understand their exposure. Beginning in early 2024 and continuing through 2025, the NVD experienced a prolonged enrichment backlog. Thousands of CVEs went without proper analysis. That means security teams couldn’t get accurate information about emerging threats because the people who normally provide that information had been reduced or removed.

You can track this in real time at the NIST NVD backlog status tracker. The data is public. The backlog is persistent. And it exists because NIST has faced the same staffing and funding constraints that have hit every other federal security agency. This is what I meant about deferring costs rather than eliminating them. That backlog doesn’t disappear. It just means that when the next major vulnerability is discovered, the analysis and coordination that normally happens in weeks might take months. The vulnerability doesn’t care about your budget cycle.

What We Should Actually Be Learning

I’m not arguing that federal IT spending is optimal. It isn’t. I’ve seen tremendous waste. I’ve seen projects that cost multiples of what they should have. I’ve seen staffing that could be rightsized. But there is a meaningful difference between rightsizing and gutting, and the current approach has confused the two. These systems have spent decades accumulating organizational knowledge, security posture, and institutional memory. You don’t rebuild that quickly, and you certainly don’t rebuild it while you’re still running the same infrastructure 24 hours a day.

The real lesson here isn’t in how to cut federal IT costs effectively. It’s in how to make cuts that create crises you don’t immediately perceive because they unfold across systems too complex for quarterly reporting to capture. The Treasury access incident, the CISA staffing gaps, the NVD backlog, the vulnerability coordination failures waiting to happen when sophisticated threat actors probe networks that aren’t being actively monitored the way they used to be. These aren’t separate problems. They’re symptoms of the same approach to infrastructure management, and they’re going to compound.

I’m interested in your experience here. If you’ve worked in federal IT or federal cybersecurity, I’d want to hear what you’re seeing on the ground. If these cuts have affected systems you work with or depend on, what specific gaps are you noticing? This isn’t abstract policy discussion. It’s operational reality that will shape security posture and infrastructure resilience for years to come.

DOGE’s Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure

By Milton Harris on March, 2026. Posted in Uncategorized.

The Scale of the Cuts and What They Actually Affected

When the Department of Government Efficiency began its work through 2025 and into 2026, the cuts came fast. The Social Security Administration, Treasury Department, and Cybersecurity and Infrastructure Security Agency all saw staffing reductions measured in hundreds, not dozens. We’re talking about thousands of IT and cybersecurity personnel across the federal government losing their positions over a compressed timeline. If you’ve ever worked in a large organization, you know that’s not a gentle adjustment. That’s a structural shock.

DOGE's Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure
DOGE’s Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure

The specific numbers matter because they tell you something about the decisions being made. CISA, the federal agency responsible for coordinating responses to cyberattacks, lost an estimated 130 employees in early 2025 alone. That’s not a budget line item. That’s 130 people who knew where the vulnerabilities were, who had relationships with private sector security teams, who understood the threat landscape because they’d been watching it for years. You don’t replace that kind of institutional knowledge quickly, if at all.

Illustration for DOGE's Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure
Illustration for DOGE’s Federal IT Cuts Are a Masterclass in What Not to Do to Legacy Infrastructure

The Vulnerability Database Backlog Nobody’s Talking About Enough

Here’s where the cuts become genuinely dangerous in a way that compounds over time. The National Institute of Standards and Technology maintains the National Vulnerability Database, a central repository where every known security weakness in software gets cataloged and analyzed. Starting in early 2024 and continuing through 2025, this database fell into a severe enrichment backlog. Thousands of vulnerabilities discovered by researchers sat waiting for analysis, without context, severity ratings, or the detailed information security teams need to prioritize fixes.

The reason? Funding and staffing constraints at NIST. When you have fewer people with less time, something has to give. In this case, it was the systematic review process that keeps the vulnerability database current and useful. You can check the NIST NVD backlog status tracker yourself to see how this played out in real time. The dashboard shows exactly how far behind the enrichment process fell. For security teams trying to understand what they need to patch and in what order, this wasn’t a minor inconvenience. It was working without a map.

The Treasury Access Incident and What It Signals

In February 2025, something happened that should have triggered an immediate response. Personnel affiliated with DOGE gained access to the Bureau of the Fiscal Service payment systems at the Treasury Department. These systems process over 5.45 trillion dollars in annual federal payments. Not million. Trillion. This wasn’t a theoretical security risk. It was a real person with real access to systems that move the money funding everything the government does.

Congressional oversight hearings followed. The incident got attention because it had to. But what most people missed is what it tells you about access controls and personnel vetting across federal IT infrastructure. When staffing is stretched thin, when people are overwhelmed, when institutional knowledge about who should have what access is distributed across people being laid off, these incidents become more likely. The Treasury breach wasn’t a one-off failure of a single system. It was a symptom of broader fragmentation happening across federal IT.

What Former CISA Leadership Actually Said About This

Jen Easterly, who led CISA through some of the most significant cyber threats the nation has faced, testified in early 2025 that reducing federal cybersecurity staffing during a period of heightened nation-state threat activity represented a “strategic own goal.” That’s not hyperbolic language from her. That’s a careful assessment from someone who spent years inside the system understanding threat actors like Volt Typhoon and what it takes to defend against them. She was saying, publicly and under oath, that we were making ourselves more vulnerable at precisely the moment we needed to be stronger.

The timing matters. Volt Typhoon and similar state-sponsored groups have been actively probing federal networks for years. Their approach is patient, methodical, and designed to persist undetected. They’re not looking for quick wins. They’re building infrastructure for potential future use. When you reduce the people whose job it is to detect that activity, you’re not saving money. You’re paying a different cost later.

The Forecast: Where This Actually Goes

Here’s what I think matters most moving forward, separate from the political debate about the right size of government. Legacy infrastructure at the federal level runs on institutional knowledge that lives in people’s heads. It runs on relationships between agencies. It runs on continuity. The cuts we’ve seen violate basic principles of how you manage complex systems. You don’t strip staffing from critical infrastructure during times of threat escalation. You don’t lay off the people who understand your payment systems. You don’t reduce your cybersecurity workforce when nation-states are actively probing your networks.

Over the next 12 to 24 months, expect second and third-order effects. Vulnerability databases will fall further behind. Incident response times will lengthen. The ability to coordinate across agencies during a serious breach will degrade. Some of these effects will be visible. Some won’t be until something fails spectacularly. The CISA workforce reduction coverage at CyberScoop captures some of the immediate concern, but the real impact unfolds over time.

If you work in infrastructure, security, or systems engineering at any level, this should concern you. It illustrates what happens when you treat complex systems as simple cost centers. The lessons apply far beyond federal government, to any organization considering rapid staff reductions in critical areas. I’d be interested in hearing from people who work inside these agencies or have insight into how these cuts are playing out operationally. What are you seeing? What’s broken that people outside aren’t talking about yet?

Older Posts Newer Posts