The four-year-old typo that nobody can fix 🧟 and more about building developer tools

#api #discuss #softwareengineering #tooling

As the host of Making Software I get to have some pretty real conversations about what it actually takes to build good software. And in my recent chat with Raghd Hamzeh (Senior Software Engineer at Okta and a core maintainer of OpenFGA) hit home for me.

We talked about a side of engineering that doesn’t get enough airtime: what happens when your users are other engineers? If you’ve ever built an API, an SDK, or even just a shared library, you know that developers are the most rewarding, but also the most "vocal" audience you can have.

Here are the three things from our conversation that have been living rent-free in my head:

1. The "Breaking Change" Itch is Real 😬

Raghd admitted something that I think a lot of us can relate to: when there’s a four-year-old typo in one of the products you're building, that drives you crazy. It could be just a small naming inconsistency, but when it’s there, it's staring back at you every time.

We got into that internal battle every maintainer knows: do you break everyone’s build just to satisfy the need for a clean API? Probably not. But it’s a powerful reminder that the decisions we make in Month 1, like how we pass a parameter, become the legacy we have to live with in Year 5.

2. Stop building "Alien" SDKs 👽

This one got personal! While coding on the Ruby SDK for OpenFGA, I ran into this head-on. Rubyists are opinionated (I should know, I’m one of them).

When you’re building multi-language tools, you’re constantly balancing two things:

Consistency: Making sure the Go SDK and the Python SDK behave the same way.
Idiom: Making sure a Ruby dev doesn't feel like they're writing Java code with extra steps.

Raghd’s take? You won't get it perfect 100% of the time. Sometimes, you have to prioritize the long-term health of the platform over a "perfectly idiomatic" implementation just so the project stays maintainable for the team behind it. That tension never fully goes away, you just get better at navigating it.

3. The "AI" file that’s actually for humans 🤖

With the rise of AI, everyone is adding agents.md files to their repos. Raghd had a spicy take: Write that file for your human contributors first.

If you want people to help you build your open-source dream, lay out your expectations clearly:

How should commits be structured?
What does the core architecture look like?
Should contributors open an issue before submitting a PR?

Documenting these "non-code" decisions up front saves an enormous amount of friction. It turns "This PR isn't what we wanted" into "Here is the blueprint we’re all following."