The story of belongingfour days beforeNext in my adventure across the coherence narrative realm is the story…Developer surface

Hosting and hosted API design perspectives2021When discussing API design strategies, I keep running into this distinction. It…I mentioned this concept before, and I feel like it’s worth expanding on a little bit. If we are in the business of making a product that developers rely on to create user experiences, the developer surface of this product is the union of all means through which developers create these experiences.

Edgewise Thinking2023I stumbled into this framing when talking about product/platform thinking with my…Let’s unpack this, starting with a simple case. Suppose you and I decided to ship a library that has one function. Applying the definition, that library is the product and its developer surface is the function. Easy, right? As our product becomes popular, we start noticing something weird. Remember that one-line file where we track the version of the library, just for ourselves? Well, turns out some developers started using its contents in their build. So when we thought — “oh hey, let’s just delete that file, we don’t need it anymore” — all hell broke loose? That file became developer surface, too!

Heuristics will be discerned and codified2021Here’s another developer experience pattern that I’ve noticed. When designing APIs, we…In mature developer-facing products, the developer surface becomes far more than just the API. Shipping samples along with the library? Yep, these are part of the developer surface, too. Got some clever heuristics deep in your code? Or maybe just bugs? Hyrum’s Law captures beautifully the spirit of this phenomenon:

Caring for elephants2022Unlike dandelions’ obsession with excitement, elephants tend to want their dependencies to…With a sufficient number of users of an API,
it does not matter what you promise in the contract:
all observable behaviors of your system
will be depended on by somebody.

Shadows and Curses2022The second curse can be seen as the interplay between “ 🔮…This sufficiently high number of API users can truly mess with what is or is not a developer surface. While we imagine the contract with developers as a crisp document of high transparency and clarity, we are usually mesmerized by the messy innards that are the outcome of developers just trying to get things to work. Even messier in comparison will be our attempts to convince developers to use the APIs the way we intended.

Live as our customer2023This principle is something that feels very intuitive at first blush, but…Build a thing to build the thing2023When building new products, there’s always a weird tension between making something…Polarity-based API layering2021While discussing API design, one pattern that caught my eye was polarity-based…The developer funneltwo days afterIf I ever chatted with you about developer experience in person, I’ve…The structure of a principlelinks here, 2021Our team ships a developer surface to both internal and external customers.…The platform two-steplinks here, 2022This technique is something I find employed quite often by teams that…Layer gapslinks here, 2023Layer gaps are when a developer surface layer fails to close fully…Porcelainslinks here, 2023The pattern goes like this. When we build our own cool thing…Doers, Thinkers, and Magicianslinks here, 2023Let’s suppose that you and I are spinning up a new developer…Makers and Magicianslinks here, 2023We’ll define the first circle as people who develop software, whether professionally…When we embark on a project that intends to ship a developer-facing product, it’s worth planning the work and structuring the team in a way that anticipates this messiness. We are not writing the developer contract. Developers write the contract with us, and frequently, their contributions carry more weight. Walking this line of carrying our original intention while having awareness of where the developers want to take is not something that comes intuitively or easily.