Building Better User Experience for SDK Products — Three Lessons Learned

Photo by Arget on Unsplash

Before getting into the topic, let’s talk a little bit about SDK in general. SDK (software development kit) is a vague term. It can be big or small. Sometimes the term is used interchangeably with API (application programming interface). But they are different. To give it a simple definition, SDK is packaged APIs. Think about romaine lettuce (API) and romaine salad. In that sense, API is the main ingredient, but not everything. SDK is the product, even though it may not be sold or monetized as a stand alone product.

Most SDK products require specific coding skills and technical knowledge in a certain domain. Easy to use is not their signature trait. Anyone who has spent time plowing through limited documentation and poorly noted samples knows how hard it can be to implement a SDK. But with the proliferation of cloud based services, things started to change. Now you have companies like Stripe and Twillio that are built on top of SDKs they offer. Getting developers adopting the SDK with less effort in shorter time is ever more critical to survive in the competition.

For the past year and half, I had the opportunity to manage SDK as part of the product offering at a hardware company. I came to the job as someone who had worked extensively as a designer and user experience expert. I was able to bring in new perspectives, a lens through product value proposition and user experience. But managing and growing such technical products also poses a lot of challenges. Here are some of the lessons I learned and am continue pondering.

Pay close attention to on-boarding experience

Here I define on-boarding experience as from signing up to be able to successfully integrate the SDK and accomplish some basic tasks that the SDK is set up to do. In our case, it’s to scan and read the first barcode or RFID tag using our scanners or readers. Of course there are marketing activities go beyond both ends. For this discussion, let’s just limit to people who already decided to sign up for the SDK program. Even with this limited scope, on boarding process is far more complex than it looks, since it inevitably touches various systems such as customer management, payment, app key or token management, product life cycle management (if you are dealing with hardware as well).

On boarding experience can be easily underestimated when developing business and enterprise applications. If you ask, everybody agrees that on boarding is important. However, when internal processes or technology setup are in conflict with user experience goals, many companies opted to bend their customer experience to fit for their internal processes, to save money, or time, or both. This could be a four page long sign up process because some teams want to get certain information from new users even when it is not necessary; or asking tricky security questions because that happens to be what a 3rd party component is looking for; or some limitations with an old database; The list can go on and on. The impact to the user experience can be inconspicuous and yet very detrimental.

Usually SDK plays a complementary role to the products or services a company offers. As a product, SDK often was created to meet its creator’s own engineering needs or the need of some advanced customers. On the other hand, when companies seek solutions through SDK, they are willing to take some effort making their way through different kind of issues, and often appear to have a higher tolerance level to issues with the SDK. This could mislead the SDK creators to pay less attention to user experience issues. To be fair, engineering teams care about usability and often advocates for better usability strongly. However, what the team sees and experiences are often different from what customer experiences. The engineering priorities are not always aligned with the user priorities. Without proper measurements and feedback loop, even good intention will often result in unintended consequences. The on boarding experience is often an epitome of such disconnect.

It took us months to iron out issues with signups and app keys. Because app key is embedded in the SDK, how to conduct extensive testings and catching issues before they spill out to the developers turned out to be a big challenge. Being a small company with limited resources, we also suffered heavily from the issue mentioned earlier: we tried to bend our on boarding process in many places to deal with our systems, as opposed to optimize our system to work for our users.

Less is more

Stay focused on the core competency probably is the hardest thing in product development. And this is particularly true when managing a SDK. For a SDK to be useful, you want it to have powerful features, to be accessible through different ways, can be coded using different tools. One of your big customers is entertaining the idea of developing an app using cross platform tools, should you support? A new framework is getting increasingly popular, hopping on that wagon as well?

Here are two common pitfalls that should watch out for. I want to point out that these are the pitfalls that many products face, but could be more subtle for SDKs and therefore more deceiving.

  1. expansion pitfall
    Here I’m referring to adapting the SDK to support more platforms, programming languages, frameworks but not necessarily adding features. At the beginning, this is not only useful but often critical to get on the right platforms. Our SDK started as a Windows based SDK, supporting both desktop and Windows Mobile. By switching the focus on fully embracing mobile technologies by supporting iOS and Android, the company was able to survive the wave of mobile computing and thrived. But supporting a platform is not a one time effort. Once the work is out, you are liable for serving your customers what you claim to serve. You will need to help customers address their issues, constantly test and retest, and to keep things up to date, After all, SDK is a toolkit built with a lot of tools and is aimed at to serve many other tools. Where should we draw the line? Here’s a quick example: our SDK supports iOS natively. To support Xamarin, so people who are using C# for their app development can also integrate our SDK in their projects, we will need to create bindings to work with Xamarin. Anytime we update our iOS SDK, we need to update the binding. Any time iOS has a major update, instead of testing one thing, we need to test all three of them. When a customer reports some issue with their Xamarin integration, we might also need to go through all three components to find out. When the supporting work is skipped, compromised or rushed, it will take a big toll on the quality and the experience for the developers.
  2. louder voices pitfall
    There are opinions, ideas, requests both from within and from outside when building a product. This is a good thing, but not always. When there is no systematic way of collecting, analyzing feedbacks objectively, two things might happen. Externally, customers who actively give lots of feedbacks and are very vocal about what they want tend to get things going their way. Internally, people who’s got a strong opinion and speaks with a lot of weight can also swing the development and drives feature creeps or unnecessary SDK expansions.

I looked into our developer support emails for certain period. The least popular development environment we support drew the most support calls or emails. On the other hand, our most popular platform, which is iOS, has the least support issues. There are many reasons. For one, our iOS SDK has been tinkered for years and many issues have been ironed out. But obviously as our SDK expands into new programming environments, new platforms, the gains are getting smaller while the effort is piling up, and inevitably, the quality is compromised.

This is not to say that you absolutely don’t want to expand. But you do need to be aware of the cost, and try not to underestimate the effort. A full circle is better than ten broken paths.

A full circle is better than ten broken paths

When planning for features and platforms, companies should regularly evaluate the impact each platform/features really makes, and their true cost. The 20/80 rule has been widely recognized, studied and understood. The real challenge is to recognize the dynamics, making adjustments, adapting to the changing context timely.

Communicating the core values

Most home grown SDK evolves organically. Over time, it gets bigger and more complicated. And the creators, who are so often either busy chasing new features, new capabilities, or solving bugs for the new features or new framework support, fail to recognize that the core value of the SDK, which seems so natural to them actually may not be obvious at all to the customers. New comers frequently get lost in the technical details and find it hard to grasp why and how they should use the SDK in the first place.

It is true to internal people too. New team members, and people who have a stake but don’t track the status of the SDK very often, all can benefit from some good use cases, stories or projects why they need to do this in the first place.

I experienced first hand that good case studies and customer stories helped the team build the connection with customers. We were trying to collect feedbacks from the engineering team on some of cases and videos the marketing team created to make sure the content is accurate. We got unexpected feedback that the videos helped them too: Not only they get to see the impact of their work, seeing the product in action also helped build emotional connection to the product and its value.


All of the three lessons look pretty obvious from outside and hindsight. In practice, it is so easy to forget about the basics and falling into the traps of busy chasing fancy features, beautiful numbers, and growth hacking techniques. This essay is not a how-to guide. It serves as a reminder that SDK, if promoted as a product, needs to be treated as a product. And we should think about the user experience holistically.

Product manager by day, tinkerer by night. I write about design, technology and better ways to make things.