Dion Almaer

Software, Development, Products

Developer Platform

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

Developer Docs + GenAI = ❤️

We can do so much to help tech writers scale their efforts and help developers learn!

I know, I know, the current hammer du jour is “GPT for X“.  It behooves us to explore how a promising new technology can help us, and I believe there are two large reasons we should do so:

  • We (industry wide!) need all the help we can get to scale quality developer docs, so using these tools to help anyone writing the docs be productive is hugely valuable.
  • Developers are already looking at products like ChatGPT3 and asking questions of them. Currently the quality is variable depending on what is being used and the corpus that’s been available in the time window. We need to make sure that usage results in useful high quality output.

Helping produce quality developer docs

Every developer product or platform runs into the struggle of keeping high quality documentation up to date and comprehensive. It’s hard enough to execute on reference docs, let alone conceptual docs, tutorials, etc.

There is a resourcing issue at the heart of this:

  • It is very hard to hire great technical writers, because they need qualities such as:
    • Highly technical like an engineer
    • Able to explain and teach concepts
    • Write well.
  • Most (but not all!) engineers aren’t comfortable with taking on the writing aspects of their APIs
    • To scale, engineers, product managers, and developer advocates are needed to take on certain aspects of their docs (just can’t hire enough tech writers!)

GenAI isn’t a silver bullet, and no one would suggest we let the machines generate our documentation, but rather it can be a tool for the humans that do the writing!

  • As you write the docs, you can get various examples from a GPT-like engine that you then refine. ChatGPT3 is able to do a solid job at some of these tasks already, and is only going to get a lot better.
  • To take it to the next level, you can use techniques to refine such as few shot learning, fine tuning, or chaining so the engine can bias towards your view on best practice for whatever you are documenting. E.g. we can train on existing docs, sample code, etc.
    • Imagine including the ecosystem here too. Any great examples of content can be included in the training corpus. Just as some open source projects include the test suites from popular ecosystem libraries to make sure they aren’t broken in CI, you can do the same for content.
  • It will be great to be able to bring in not just knowledge, but also style and tone. It’s fantastic to unblock writer’s block by throwing raw content down and having the tools work for you. There are already tools that let you do things like:
    • Summarize this for me
    • Give me a good heading / title
    • Make this more concise
    • Flush this out with code examples
  • Boilerplate and grunt work… be gone.

These tools can give confidence to those who aren’t professional writers, which is huge!

Beyond docs, towards assistive learning

Helping create fantastic docs is itself a huge win for developers getting the most from your platform in a productive way. I just saw Codesphere sharing some results after they took the time to tune their docs.

But this work goes even beyond improved docs for devs.

You are now able to use the LLMs that have been tuned to your platform in other ways:

  • A chat interface for your platform knowledge
  • Get questions that target the knowledge that developers can use to train themselves
  • Integrate with popular IDEs so the information is there right where they are coding
  • …

Every day we see new examples of this, such as docs search like this:

There are a lot of challenges to go along with the opportunity, but it isn’t hard to imagine a world where you are pair-programming with Shopi and working with the GraphQL APIs is so much easier because of it, or Hydrogen components are being written for you that you can take and tweak, or converting from tech A to B is made trivial, and sooooo much more.

The tech is only getting better, let’s get on board now!

What do the bots think of this idea?!?

It felt appropriate to ask our robot friends for some of their thoughts on the topic, and here are a couple things that emerged:

Challenges of Automation in Technical Writing

As with any automated process, there are certain challenges that come with using GenAI in technical writing. One of the primary challenges is the potential for errors due to the automated nature of the process. While GenAI can help streamline the writing process, it cannot always guarantee accuracy. Additionally, GenAI may not always be able to capture the nuances and complexities of human language, which can lead to misinterpretations and errors.

Another challenge is the potential for bias in the automated process. GenAI relies on the data that is used to train it, and if the data is biased, then the output of the process can be biased as well. This can lead to incorrect or misleading information being generated.

Finally, there is the challenge of cost. GenAI can be expensive to implement and maintain, and it may not always be feasible for organizations to invest in the technology. Additionally, there may be a need for additional personnel to manage the process and ensure accuracy.

Benefits of Using Machine Learning in Technical Writing

Despite the potential challenges, there are several benefits to using GenAI in technical writing. One of the primary benefits is the potential to increase productivity. By automating certain aspects of the writing process, GenAI can help streamline the workflow and reduce the amount of time spent on manual tasks. This can help to free up time for more creative and complex tasks.

Additionally, GenAI can help to improve the accuracy of the writing process. By leveraging the data used to train the system, GenAI can help to ensure that the output is consistent and accurate. This can help to reduce the amount of time spent on manual proofreading and editing.

Finally, GenAI can help to reduce costs. By automating certain aspects of the writing process, organizations can potentially save money on personnel costs. Additionally, GenAI can help to reduce the amount of time spent on manual tasks, which can lead to cost savings in the long run.

Integrating GenAI into Existing Technical Writing Processes

Integrating GenAI into existing technical writing processes can be a great way to increase efficiency and accuracy. By leveraging the power of machine learning, organizations can potentially reduce the time spent on manual tasks and improve the accuracy of their documentation.

However, there are certain challenges that must be addressed when integrating GenAI into existing technical writing processes. One of the primary challenges is ensuring that the data used to train the system is accurate and unbiased. Additionally, organizations must ensure that the system is properly managed and monitored to ensure accuracy and prevent errors.

Finally, organizations must also consider the cost of implementing and maintaining a GenAI system. While the potential benefits are great, the cost of implementing and maintaining the system must be weighed against the potential savings.

Overall, integrating GenAI into existing technical writing processes can be a great way to increase efficiency and accuracy. However, organizations must ensure that they address the challenges associated with the process and consider the cost of implementation and maintenance.

Measuring Success when Using GenAI in Technical Writing

When integrating GenAI into existing technical writing processes, it is important to establish metrics for measuring success. This will help organizations to determine if the process is working and if any changes need to be made.

One of the primary metrics for measuring success is accuracy. Organizations should track the accuracy of the output generated by the GenAI system and compare it to the accuracy of the output generated by manual processes. This will help to determine if the GenAI system is providing more accurate results than manual processes.

Another metric for measuring success is efficiency. Organizations should track the amount of time saved by using the GenAI system and compare it to the amount of time spent on manual processes. This will help to determine if the GenAI system is providing more efficient results than manual processes.

Finally, organizations should also track the cost of implementing and maintaining the GenAI system. This will help to determine if the cost of the system is worth the potential savings.

Overall, measuring success when using GenAI in technical writing is essential for determining if the process is working and if any changes need to be made. By tracking accuracy, efficiency, and cost, organizations can determine if the GenAI system is providing more accurate and efficient results than manual processes.

Developing Best Practices for Using GenAI in Technical Writing

As with any new technology, it is important to develop best practices for using GenAI in technical writing. This will help to ensure that the process is efficient and accurate, and that the output is of the highest quality.

One of the primary best practices is to use data that is accurate and unbiased. This will help to ensure that the output generated by the GenAI system is accurate and unbiased. Additionally, organizations should ensure that the data used to train the system is regularly updated to reflect any changes in the industry.

Another best practice is to ensure that the system is properly managed and monitored. This will help to ensure that the system is functioning properly and that any errors are quickly identified and corrected. Additionally, organizations should ensure that personnel are properly trained in using the system and that any changes to the system are properly documented.

Finally, organizations should also consider the cost of implementing and maintaining the GenAI system. This will help to ensure that the cost of the system is worth the potential savings.

Overall, developing best practices for using GenAI in technical writing is essential for ensuring that the process is efficient and accurate, and that the output is of the highest quality. By following these best practices, organizations can ensure that they are getting the most out of their GenAI system.

And engineer and a robot working together to create better docs.

/fin

The rise of the extensible app platforms

I was excited to see Kenneth and his team ship the public beta of the Stripe App platform:

I was excited to dive into it, as I know that the developer experience would be high quality, and I wasn’t proven wrong. Great CLI experience. Great docs. What you have come accustomed too. As I read through the anatomy of what you are able to do with apps, I could see a lot of similarities with Shopify’s app platform.

The body of a Shopify store

Let’s dive into some anatomy. When chatting with one of my favorite new PMs, Ben Sehl, he shared an analogy of how a store is like a body… a metaphor which I will now abuse to kingdom come:

When you create a Shopify store, you get a simple, yet fully functioning experience… like a human with simple attire, let’s call them Shopi. How do you want to take this base and make it your own?

The first step that products and platforms give you is the ability to tweak the look and feel. This is where you start with theming. You can dress up Shopi in many ways, and make them unique. You can make the clothing yourself, or you can find manufacturers (theme developers!) that have pre-built quality goods that you can then customize from there. As the platform matures, so does the supporting ecosystem.

Now, there is a lot that you can do with the look and feel, but you quickly find that you need richer customizations. This is when the app platform comes in (often called plugins/extensions). The platform controls what can be extended. Can you replace limbs? The heart? The brain? How do you do this in a way that doesn’t destroy the body? A great platform allows for layers of extensibility, which is as much art as science. This is the type of work I love doing, and I am excited to see Shopify continue to refine these layers.

Shopify Flow: Helping you automate workflow

Systems such as nervous, circulatory etc can be the glue that makes everything work well. This is the platform doing its job at regulating everything. Connecting things and making sure any one extension doesn’t blow things up. Acting as an engine for connectors and workflows like Shopify Flow.

If you look deeper at Shopify and the Stripe platform, you see a variety of surfaces that offer extension points… e.g. the Stripe Dashboard, or the Shopify Admin. These surfaces have specific extensions with rich context. They offer embeddable UI points, with building blocks to have your extensions fit in (e.g. components that feel consistent for the users of that surface). These extensible app platforms have a variety of surfaces. In Shopify, you can ship an app that enhances the Admin for merchants, or Checkout for users, and more.

NOTE: I was particularly excited to see that Stripe is using the open source remote-ui library that we created and use in Shopify:

Ok. So, at this point, Shopi, is looking great with awesome clothing, a bionic arm, Tony Stark’s heart, and AR glasses. But you may want to customize EVEN more. This is where custom storefronts come in for Shopify. You can tie into the nervous system still via API (GraphQL or REST), but the body can be entirely different… with you building many more layers as you eschew the defaults. It doesn’t even have to be a binary choice… you should be able to weave together custom and the core headful experience.

I look forward to a future where merchants can customize their own Shopi to be exactly what they need, working with the foundations that Shopify gives them, and the creativity and skill of the developer ecosystem to provide apps, themes, and custom storefront work.

I’m also excited to see more extensible app platforms such as Stripe’s, and we share ideas and technology to raise all of the boats.

Extensibility is going to go from changes to the appearance, to bionic improvements, to providing genetic modifications.

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