What API Providers Can Learn from the Lego Developer Experience

Lego is not the first thing product owners would think of when looking for a model onboarding process. But they should. At least that is Cristiano Betta’s theory over at his blog, who will tell you the lessons you can learn for your API from the Lego onboarding experience. 

The first thing Lego does right starts with the box. Lego knows that its users are little kids who might not know much about Lego, might not initially be very inspired to spend hours building something and might have no idea to how to get started. That’s why on every box they show you not only the finished product, but what the parts are made of and some basic assembly steps. This does several things: it inspires you to build and it gives you a little handholding to make sure you have the confidence to get started. 

This is something too often API developers forget about. Many API clients are going to know nothing about your product or even the industry of which it’s a part. They probably won’t have your depth of technical experience. You need to give them the information and confidence to get started as well as providing them with motivation so they can build new things with your API that maybe you never even thought of. 

The first thing you need to do is therefore inspire developers, to make them think you’re going to solve their problem. Cristiano gives Pusher as an example of an API product that gets this right. On its site, it has a demo that shows you in a few seconds, without boring you with technical details, how you can push an event to any browser with their product. Pusher gives even very inexperienced devs the feeling they can do what they want with its products by simply steering clear of jargon like websockets and using video and imagery where possible.

Once you’ve inspired people enough to give your product a shot, you need to make getting started a piece of cake. Here again is where Lego shines. Its instruction manual is a great Get Started guide. It shows customers how to go from zero to hero in a few pages with no text and no technical explanations; just little baby steps that help them to reflect and repeat if there’s a mismatch between what they did and what’s in the guide. 
Its guides show you how to do things like create structurally sound objects according to patterns you’ll find in architecture and engineering without ever resorting to jargon. 

In terms of your API, getting started means helping a developer make their first API calls and then their first product. For this, your API needs to be forgiving like a Lego set. That is, you can let the user try something, make a mistake and then learn from their mistake, take a step back and then go on. This lets people try satisficing, a process which involves trying the first thing you think might help and then tracking back to the last known step that was correct if it doesn’t work. 

In an API or SDK, you can do this by adding detailed error messaging for every important API call. You need to signal to the developer what mistake they made. This is especially important when you have two function calls that could easily be confused, like two lego pieces. Ideally, though, as a product owner, you’d remove any ambiguity and make sure calls were different enough that someone couldn’t confuse them.

The last lesson, and one easy to forget, is to keep in mind that your tool can have many different uses, not just the ones you expect. Lego embraces this idea by offering a product, Digital Designer Virtual Building Software, where you can share new ideas for Lego products. If your product receives more than 10,000 upvotes, Lego will turn it into an official boxed product and release it to the market. You then get named a Master Builder.

This is something else that API creators too often forget. Congratulating people on building something new. Cristiano built an app for Alexa, and after a bad onboarding experience he eventually got his app accepted. Did he receive any thanks or acknowledgement for his hard work? Nope.

Cristiano concludes by emphasizing that if you want developers to succeed on your platform, make sure you acknowledge their efforts and celebrate success. 

Be sure to read the next Developer Relations article: When to Use the Three Styles of API Documentation

Original Article

Developer Experience lessons from LEGO