Week of 2021-10-18
The language frames the story
Suppose you’ve said to me that “the falling maple leaves whirl in a delicate dance with the gentle breeze.” It’s late fall, so it feels like a reasonable thing to say. The trouble is, my language only has words like “eat, fight, run, here, that, there, now, later.” I might be fascinated by what you’ve said, but get very little out of it -- and even less to pass on to others. At best, I will point at the sky and say “that!” and bulge my eyes meaningfully.
This might seem like one of those -- duh! -- obvious observations. Of course the language frames the story. However, I am finding that I easily forget this in the contexts of teams and how they are organized. To communicate with each other, teams establish a common language, a set of semantic shortcuts that allow them to work together effectively. This is where the non-obvious bits hide. This common language also frames what is being communicated.
For example, let’s imagine a hypothetical organization where communicating strategy across teams is done through a list of annual objectives and key results (OKRs). There is a process to assemble them into a coherent whole. When it’s all said and done, the story written in the language of OKRs tells where we will go next year.
However, some of our desired destinations take longer than a year to reach. To communicate these destinations, we need a language that can describe ideas that last longer than a year. Can you guess what happens when we try to express them in the language that only speaks in year-long sentences? Sure, within teams there might be long-term thinking and sound strategic artifacts. However, given the pidgin of annual OKRs that prevails outside, it is unlikely that these artifacts survive cross-team communication. The multi-year ideas will be neatly chopped or scrunched into the one-year box -- rendering them as useful as my eye-bulging-while-pointing.
If I am lucky enough to work in an organization full of brilliant individuals, I will also start seeing these folks adapt to the common language. More and more, I will see how they pick out ideas that fit within the language to reduce the friction, making sure that only year-long journeys are those that count, whether in impact or attention of leads. Sure, there will still be the linguistic idealists who rail helplessly trying to overcome the limits of the OKR pidgin, but those will eventually give up and leave.
While the organization wonders why it struggles to think strategically, it might be worth it to examine the language it uses to organize itself. Is the language flexible enough to accommodate both short-term and long-term destinations? Are all ideas that matter expressible in the semantic shorthand that everyone is expected to speak?
🔗 https://glazkov.com/2021/10/21/the-language-frames-the-story/
Developer surface
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.
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!
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:
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.
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.
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.
🔗 https://glazkov.com/2021/10/18/developer-surface/
The developer funnel
If I ever chatted with you about developer experience in person, I’ve probably drawn the developer funnel for you on the whiteboard. For some reason, I always draw it as a funnel -- but any power-law visualization can suffice. As an aside, I do miss the whiteboards.
At the bottom of the funnel, there are a rare few who know how to speak to computers as directly as humans can. Their perspective on writing data to storage involves programming a controller. As we travel a bit higher, we’ll find a somewhat larger number peeps who write hardcore code (usually C/C++, and more recently, Rust) that powers operating systems. Higher still, the power law kicks into high gear: there are significantly more people with each click. Developers who write system frameworks are vastly outnumbered by developers who consume them, and there are orders of magnitudes more of those who write Javascript. They are still entirely eclipsed by the number of those who create content.
With each leap in numbers, something else happens -- the amount of power passed upward diminishes. Each new layer of abstraction aims to reduce the underlying complexity of computing and in doing so, also collapses the number of choices available to developers who work with that layer. Try to follow the rabbit trail of setting a cookie value, a one-liner in Javascript -- and a massive amount of work in the browser that goes into that. Reducing complexity makes the overall mental model of computing simpler and easier to learn, which helps to explain the growing number of developers.
This funnel can be a helpful framing for a conversation about desired qualities of the API. Do we want to have rapid growth? Probably want to be aiming somewhere higher in the funnel, designing convenient, harder to mess up APIs. Want to introduce powerful APIs and not worry about the sharper edges? Expect only a small number of consumers who will understand how to use them effectively.