Dion Almaer

Software, Development, Products

Platform Thinking

Piece Together Your Platform with Lego Blocks, Sets, and Kits

I love my layer cakes, and recently spoke about layered design systems that allow for developers to jump in at the layer that makes sense for them, and allows for maximum emergence of value.

When building a layered platform, I often think of the world of Lego and how utterly fun and creative that universe is. I aspire to enabling developers in the same way.

I mentally split things up into the concepts of: blocks, sets, and kits.

A pile of LEGO blocks

Blocks

Lego blocks are the base level primitives that exist for the platform. They offer clear capabilities, and have interfaces that are as universal as possible.

On the interface side you have the way the the tubes on the bottom interlock with the studs on top of other bricks. This standard allows the composability of the majority of the blocks. It’s all about the interlock and the spacing.

For capabilities, you get the specialization on top of these interfaces. Think of the engines that can be connected to the car systems to make them drivable. That engine can also be composed in a multitude of ways to deliver force for many ideas.

In our world of software, we have the same thing, with interface glue such as props with React, JSON for formats, HTTP for networks, and so on. Then when you look at a platform such as Cloudflare, you see that these are composed with infrastructure blocks such as D1 for databases that speak the language of Workers, R2 for distributed object storage, etc.

Blocks compose with other blocks. Almost anything can be created from this, the lowest of layers. And when you create a new primitive that fits the interfaces, creatively can explode with the possibility.

A LEGO car built from a set

Sets

Starting from first principles, from the lowest level of blocks, can be overly complex. In practice, someone can build the next level of abstraction that solves a problem and can share it with others.

These are patterns, or recipes, or… Sets. With Lego, you most often see people buying sets with instructions on how to build a collection. I remember getting instructions with many ideas that I could reuse blocks to create with.

In software we often see this grouping of capabilities in various frameworks, that come with their own instructions on how to put things together. At other times you see templates, where you have a starting point of blocks to give you a strong leg up. Vercel does a great job of providing these, making it easy to start building on their platform.

A LEGO car kit, very custom purpose

Kits

There is a slightly different form of abstraction on top of blocks, and that is kits. These are meant to be for a particular purpose and are more restrictive that sets. The blocks and setup fit together much better (are less blocky!) and you wouldn’t take the parts of a kit and use them to make something different.

In software, an extreme case would be a proprietary language with components that only let’s you build extensions that look and feel like the platform they run on. A kit would make sense if you wanted to be very restrictive on extensibility, and you value making it as easy as possible to do certain things, and hard to break out.

You only really want to codify kits when you are very sure that they are very common and useful. If you have a scenario where many people will want to clone and tweak, you may be on to something with a kit.

There are many valid cases for kits, but it is also true that too often companies make the choice to over-invent. It is so very tempting to create a domain specific language, or even a custom programming language. But first, consider codifying constraints using languages and platforms that many developers have spent the time to learn already, where there is community, and answers, and where AI tools have something to have been trained on 😉

You can poke and make fun of English, in the same way that you can do so with JavaScript, but there is a reason it is still thriving whereas Esperanto isn’t.

Can you see the blocks, sets, and kits in your platforms? Are they well layered?

NOTE; My good friend and “one of the best platform engineers I know”, Dimitri Glazkov, has written about these layers from a slight different lens in his great piece: 4 layers.

Help Mario Reach The Next Platform!

Don’t leave him behind, or with a jump that’s just too far!

Nothing is static. The world is moving, and it’s the job of a platform to help an ecosystem evolve at the right pace.

When the pace is good, as the screen moves right, Mario sees where he needs to jump next and can time it well. It’s fun to be in the flow jumping from improvement to improvement!

When the pace is too fast, Mario feels stuck and either disappears off screen, or does a Hail Mary jump without a real chance to land on the next platform, falling into fire in bowsers castle.

Platforms need to treat the time that developers have to spend on evolving alongside us as precious. They should strive to minimize their toil, keeping a high level of trust with the developer community.

What are the keys to success here? How should we, as platform owners, drive things? This post will detail:

  • Understanding the use cases
  • Building enough of the new platform
  • Having everything we can to help you get there
  • Sharing pieces early
  • Starting the deprecation clock appropriately
  • Staying close to the platform
  • Do you need a new platform?
Researching use cases at the library

Understanding the use cases

We need to understand Mario’s needs and why it will be better for him to be on the new platform

When bringing up a v.next of a service, the platform needs an understanding of what the current version is being used for. A new version is shipping for a reason, and there should be clarity on basic questions such as:

  • How will developers be able to deliver the functionality they are offering?
  • Are there any capabilities that are not offered in the new version yet and what is the impact?
    • When options are restricted, it’s obviously a different set of timing should be considered
  • When will replacement capabilities show up (in the cases when they do)?
  • What are the new capabilities that we will be bringing to developers and what will they unlock?

Seems blindingly obvious, but having deep knowledge here is far from universal, and past decisions are often lost, not allowing us to apply Chestertons Fence.

Gymnast landing on a platform

Building enough of the new platform

We want the new platform wide enough that Mario can stick the landing

With a strong understanding, the new platform starts the journey of getting built and iterating. It’s vital to make sure that we have an appropriate amount of it built out before sharing it with the developer community. With a minimal surface area, you are at risk of not finding enough information and thus ending up making large changes in the future, and developers are left touching a small part of the elephant and extrapolating the rest.

The more we can get the new version in close range, the better the chance we have of enticing Mario, and having him get across to the other side with a cheer.

When building the new platform, we should also make sure to do a good job with our layering. As we do this, Mario will not have to learn new things for each part of his journey, and will instead accrue understanding. Great layering also means that we will be able to compose our solutions better, resulting in less churn as we make changes. This should result in fewer massive migrations.

Mario with a Jetpack

Having everything in place to help evolution

We want to give Mario jet packs and tools to make the leap

When making these platform changes, we are often placing toil on developers. Hopefully, there is much value too, but there will often be times where the changes we impose have a strong overall ecosystem value, but maybe not always the same value for the individual developer. The tragedy of the commons are real, and we can recognize this by going above and beyond with our help for developers.

What does the jet pack look like?

World class documentation on the why and the how. This is foundational, and includes great reference docs, tutorials & workshops, and samples & solutions.

World class tooling, where developers live all day long. Linters and codemods that give clear guidance and nudging on what changes are needed. With everything that it changing with development right now (e.g. AI copilots) imagine how far we could take this? Why can’t we have a future that has platform help in our developers code editors giving suggestions, and sending PRs to GitHub with changes that keep their projects up to date. If we did this right we could change the feeling from “ugh I feel like I am constantly being nagged to make some change! $PLATFORM understands that I have features to write and a business to run!!” to “Wow, $PLATFORM is helping me keep up to date and improving my app! I can see the improvements, and merchants are loving it!”

Mario looking into the future

Sharing early

Show Mario a glimpse into what’s coming up in the level so he can prepare

The window can be pretty small for Mario, and it can be helpful to offer a view of what’s coming, as long as we aren’t flooding him with information (see: building enough of the platform!).

Depending on what kind of changes we are doing, we may be able to allow developers to play with the future pieces early.

Remix does a great job of this. It allows you to opt into future flags, and then when the future becomes the present, you are ready for it!

How does that work? Let’s look at an example. Remix 2 is coming out soon, but the changes and new features are coming online in a way that you can opt in your Remix 1.* application today. The way that you name routes and their mapping with the file system is changing from this to a new system that includes flat routes.

Instead of waiting for Remix 2, today I can update my app with a couple simple steps:

  1. Tell my v1 app that I am ready to use the new feature via a simple declaration in my remix.config.js:

    future: { v2_routeConvention: true }
  2. Update my directories and files to map to the new system

When the feature is ready, communicating it could ramp up over time. You can start small and see a few early adopters find it and offer feedback. Recently the dev server started to console.log the fact that it’s ready, reaching more developers, and more feedback can flow in.

When Remix 2 ships, those who opted in will be able to delete the future flags and everything will just work. Now picture this for a larger number of flags. I can opt in and then I will be fully ready, finding myself on the next platform without even jumping… I just kept walking and got there.

The two roads of deprecation

Starting the deprecation clock appropriately

Don’t disintegrate the current platform too early!

You know those blocks that fall away when Mario has been stood on them for a bit? I hate those. They mean I have to think really quickly, anxiety rises, and I make mistakes and fall to my doom.

While it can be great to share information on the new platform early, as discussed, we should be careful when choosing when the clock starts ticking on deprecating the existing platform.

NOTE: A recent example of this was OpenAI deprecating the Codex API where the team maybe didn’t quite appreciate that although other APIs had somewhat transcended it, the work to make changes is real. To their credit, they got feedback and changed the deprecation by at least allowing longer access in the research program.

The clock shouldn’t start until the entire new platform is built, and we have the jetpacks ready. There have been times in which we build piece A of the new and deprecate the equivalent piece on the old. The problem is that the developer can’t actually migrate everything over, and they can become stuck.

In general we should cluster our changes and have clear times for most of our developers to do upgrades (the ones who aren’t jumping early to changes).

And we should be very careful not to end up in the situation that the meme shows above, where the new platform isn’t ready and the old one is deprecated. It’s so common to as often be the norm, and we need to fight entropy to change this.

I always somewhat appreciated the fact that I could schedule time after a major iOS SDK release to update our apps. The business understood this, and we had the space to make this happen in one chunk, and get our new app into the app store ready for the consumer releases. Contrast this with a drip, drip, drip of being asked to make small changes constantly.

Very thin bricks

Staying close to the platform

Favor the lightest abstractions that aren’t proprietary. Developers should be spending their time learning the platform, not new technology for the sake of it. For example, before creating a proprietary layout system that every developer has to learn, can we use CSS with our own special variables and styles and a sandboxed container to limit it? Or instead of creating a custom abstraction to fetch content, how about using the standard fetch(), even if you have to monkey patch it to add in specific auth, just make sure it’s well tested! No uncanny valley here please. Let developers bring their skills, and StackOverflow and ChatGPT along with them.

Mario on a relaxing walk

Do you need a new platform?

Mario would be happy to walk along and maybe take some stairs?

Before falling for second system syndrome, double and triple check that the right path forward is a new platform at all, or if there are smaller steps that can be made that over time will get Mario where he needs to be.

Respecting developers time

Let’s treat the time that developers have as a precious commodity. It actually takes work to stand still, as there is no such thing as stable. Browsers are changing. Libraries and SDKs and tools are changing, and we add to that. The more we can do to minimize it by putting in work on our side, the more leverage we get across the ecosystem. We want them spending as much time as possible on amazing features for our merchants, and jumping their way to success along the way.

🍄 Let’s a go! 🍄

/fin

Agency developers are underrated

You hear about the developer who created Wordle, or who went on to found a large company, or contributed an open source project to the commons. You don’t often hear about the agency developer, and they are both important and often on their own journeys.

The Value of Agency

Agencies, and consultants, are out there helping make businesses a reality. They deliver expertise when it doesn’t exist in house. They quickly expand the workforce and when done right, leave employees better equipped for growth.

By working at multiple companies in a domain, they can bring learnings, just as employees do when they change companies as they journey through their career.

I have found that high quality agencies are true experts who have bet their business on your platform, understand your competition, and know what your users really want. They build true empathy on what it takes to be successful.

If a platform company doesn’t have programs that include agencies as a tier one cohort they are probably doing it wrong. Ask yourself:

  • Am I training the developers at agencies to have a great understanding of what my platform or product offers? If they are asked, or are given freedom to choose, what solution to build on… would they choose you?
  • Are these developers external advocates in the community? Is there a community for them to show their chops, be rewarded for their knowledge, and celebrated?
  • Does the business team at agencies understand your offering and are you supporting them so they can be an extended sales force for you?
  • Do you have agencies not only servicing customers directly, but also through self-service opportunities (e.g. building apps / extensions / themes)?

At Shopify for example, our agencies are a vital part of our ecosystem, working with us on a joint mission to be merchant obsessed as a way to improve commerce for all. As I have dived into the ecosystem I am constantly finding agencies who deeply understand commerce and our platform, and are at the heart of delivering for our merchants to make their experiences unique and high quality.

We often talk about learning the tech, and the product, but learning commerce is an important key, and agencies have a lot of that knowledge. And once you understand the domain, competition, and environment, opportunities are unlocked.

The Entrepreneurial Path

Many of the solo or small team entrepreneurial developers that I have met came from a past life working at a merchant or at agencies. That was the training ground for their knowledge.

I have seen some common patterns when getting to know our developers, including one very strong one:

“I worked at an agency working on commerce sites for $YEARS. I started to notice that several of our clients were asking for $FEATURE, so I decided that I would build a Shopify app that delivers the feature and enables any merchant the ability to unlock it!”

— Pat

This takes so much risk away from your app development. For one, you can do work for clients directly to prove things out, and this gives you a direct line to a customer with the clear need (else they wouldn’t pay!) Then by working with other merchants you can learn what needs to be customizable, and then when ready an app version unlocks scale. It’s nice to get paid decent money from a merchant to do guaranteed work, and it’s nice to get money whenever someone installs your app.

This is yet another example of the power of de-risking app development with Shopify.

Thank you agencies, and those of you working at them. You are at the heart of it all.

Others in the series:

The right thing to do, is the right thing to do.