Accelerating Technical Integrations

Chris Chandler
November 1, 2021

Research and insights into better support for API products

Frustrated with the tools available to provide support for developers utilizing a technical product such as an API, the sudoHERO team took a deep dive into the problem and is developing an innovate set of products to help companies accelerate onboarding of API-powered partnerships. Read on to find out more about what we’ve learned about the effectiveness of today’s support methodologies as well as our vision to reimagine the API onboarding experience.

What We’ve Learned

For several months, the team at sudoHERO has been working on a better way to provide support for users of technical products which require integration or complex configuration such as a developer tool or an API. The API Economy is an important and fast-growing segment of the tech industry, enabling companies to facilitate transactions between systems in a fraction of the time it would take to do so through other means. According to Programmable Web, the use of APIs have exploded over the past decade with an 1,100% increase in the number of publicly available APIs. Not used just by technology companies, APIs add powerful new capabilities to organizations across practically every service industry including finance, travel, and retail.

According to Programmable Web, the use of APIs have grown by more than 1,100% over the past decade.

Previous Research with Developers

Our startup journey began with a focus on the developer, the person who is trying to implement a technical solution in need of assistance, and we learned a great deal about the best way to share a technical support question to get it solved. The result of that work is our QuickSolve interface, a support tool which enhances the support interaction.

Upon validating our work on QuickSolve with dozens of developers with a series of usability tests, we reached out to companies across a broad range of industries (FinTech, Retail, eCommerce, Travel and Developer Tools) to better understand their pain points when supporting an API in the hopes of finding that elusive “product/market fit” which is a critical part of an early startup’s journey.

Challenges with Onboarding API Users

While talking to business, technical and support leaders across several companies, the sudoHERO team heard a great deal about their challenges in getting customers to adopt a technical product such as an API. All of the companies we spoke with had developer documentation published on their website outlining how to use the product and a support team ready to assist developers who had questions about using it. In our interviews, the most common frustration we heard from business leaders was with signing deals which required API integration, only to find many of those deals were never implemented due to challenges with integration. Giuliano Xyloyannis, Chief Revenue Officer of the fashion e-commerce giant Zalora, which offers an API to connect with a diverse range of merchants, clearly articulated the problem when he shared that “50% of issues reported by new merchants coming on board are API related.” Several other managers we spoke to had made significant investments in building an API, only to find very little usage of the service. Instead, many of their customers and partners continued to rely upon manual processing of transaction which is more time and resource intensive.

“50% of issues reported by new merchants coming on board are API related issues.” -Giulio Xyloyannis, CRO, Zalora

With this feedback in mind, we went back to developers who try to utilize an API and asked why their projects are delayed and abandoned and the top two issues we found were:

  1. The developer can’t find the answer needed to use the API, and
  2. The developer can’t find the answer needed in a timely manner to use the API.

Developer Documentation Pages are Helpful…

We found this disconnect between the company offering the API and the developer wanting to utilize it to be puzzling. The primary tool to share the functionality of a technical product is the Documentation page which every company we spoke to had published on their website. In the past few years, it’s become incredibly easy to take an API specification, import it into a tool such as Docusaurus, Postman, Readme, Gitbook, and others, to publish an up-to-date API specification for developers to reference. In a recent A16Z Future podcast interview, Jeff Lawson, CEO and founder of Twilio, offered a thought provoking comment about API Documentation: “for a developer, documentation is the ultimate marketing. …it literally describes every in and out of what the product does.” In other words, for a developer, it’s very easy to look at the specification, determine if it performs the needed function, and if so, implement it. As compared to buying other types of software, there’s no more need for lengthy sales pitches, buy-in from management, and long purchase processes to incorporate such a solution.

“…for a developer, documentation is the ultimate marketing. …it literally describes every in and out of what the product does.” -Jeff Lawson, CEO of Twilio
Image Source: Web Summit 2015 — Dublin, Ireland

Jeff Lawson’s vision for the future of API-driven business is compelling, but left us wondering… Every company we spoke to has a documentation page, so where was the breakdown between this utopian vision and reality? Going back to the top two issues reported by developers, we found that it boils down to how these technical products are supported. The primary tools used today, ticketing systems and developer forums, are either time-consuming for all parties involved, unreliable for getting an answer, or both — causing the developer to be unable to find a solution or find a solution in a timely manner and thus delaying or abandoning their integration project. To understand why these solutions are sub-par, let’s explore the mechanics of both in detail.

What’s wrong with existing support solutions?

Support options from the companies we spoke to fell into one of two categories — Ticketing Systems and Developer Community Forums. Each of these options help companies to provide support for a technical product, but present challenges for the developer.

Ticketing Systems

For the overwhelming majority of companies offering an API, especially those companies which don’t offer a developer tool, questions from developers are submitted by email and then managed using a ticketing system such as ZenDesk or FreshDesk. Intercom is a similar tool which, instead of using email, relies primarily on a chat interface, but performs the same function. When the question is received, the ticketing system sends it into a queue to be directed to the best available support rep, facilitates the communication between parties and tracks progress to ensure that it’s addressed until closed. Ultimately, the system provides important reporting data for management to assess the team’s performance in supporting its customers.

We spoke to developers to understand their impressions about receiving support through a ticketing system and found a few problems. First off, unlike other groups of customers who prefer to speak to a person when they encounter a problem, developers actually prefer to find answers by reading through information which might be of use to solve their problem before engaging a support rep. Find a snippet of code that might partly solve the problem and developers will be happy to copy it, make some modifications, and give it a try. This method of problem solving is so common on Stack Overflow that someone has created a Stack Overflow Copy/Paste Keyboard!

“It can take days to resolve simple API questions through email ticketing systems. There’s got to be a better way.” -Pete Saxby, Director of Global Sales, Bokun Software

One of the reasons why developers prefer to read about a solution vs. asking is because it’s incredibly complex to share all of the context necessary to get an answer from someone else. To accurately diagnose a problem, a countless number of variables need to be communicated to the other party in order to replicate the issue and provide a reasonable reply. More often than not, when a support request is received, some of that important context is missing, and after waiting for hours or even days for a response, the initial email support request is usually responded to with a request for clarification to some part of the question. “what version of the API are you using?”, “what’s your IP address so we can look at it from our end?”, “can you share a log file or the output?”, or other details to try and narrow down the problem to find an answer. Once provided, the message goes back into the queue and the developer waits…. again. For several of the companies we’ve interviewed, this process can go on for days until enough context is available to answer the question. Pete Saxby, Director of International Sales at Bokun Software, a leading developer of software to manage bookings for tours and attractions, shared his frustration with us. “It can take days to resolve simple API questions through email ticketing systems. There’s got to be a better way.”

As a result of the delays in answering simple questions, many developers, working on a sprint cycle, decide to delay or abandon working on the project to complete other tasks which can be closed out more quickly.

So, with developers preferring to learn how to utilize a platform by reading instead of asking for assistance, can Developer Community tools do a better job of getting a developer up and running? Let’s explore the options…

Developer Communities

Companies which build products used by developers, such as databases or containerization tools, as well as those built through an open source project, often provide support through a developer community in which users of the platform come together and help each other. Docker, MongoDB, Strapi, and Grafana are examples of companies which have built developer communities consisting of tens of thousands of developers to support their products using Discourse, a web-based forum in which users can post a question and other users can either ask for clarification or provide an answer.

The true power in these types of forums is not in providing the answer to the first person who asked, but the number of additional views the answer receives from other developers who have a similar issue. In essence, each question answered helps to build a knowledge base for future users of the forum. We analyzed several popular developer forums and found that the average forum post received 29 views/month.

The average post on a developer forum receives 29 views/month.

Jeff Atwood, founder of Discourse, summed up this benefit perfectly in a Tweet describing the core purpose of another business he founded, Stack Overflow. Stack Overflow is one of the world’s 50 most visited websites, providing community support for developers looking for assistance for many open source technologies. The true goal of Stack Overflow, as it was designed, was not to “answer my question,” but is to “collaboratively build an artifact that will benefit future coders.”

I wish more people understood that the goal of Stack Overflow is not "answer my question" but "let's collaboratively build an artifact that will benefit future coders". Perhaps SO could be doing more to educate people about this.

While developers forums can be incredibly helpful when a question has previously been asked and answered, they suffer from one major drawback — response rates. In the case that a question hasn’t been asked previously and a user posts his question, there’s no guarantee that a response will be posted from someone in the community. In fact, across the developer forums we analyzed, posts to the forum only received a response, on average, 40% of the time. Some forums allow the original poster to mark the problem as solved, and in one instance, we saw that 91% of questions had no validated answer.

Posts to the developer forums we analyzed only received a response 40% of the time.

Developer forums work best for technical products which have a high degree of reuse by a large number of users, such as developer tools. If a developer learns how to use MongoDB or Docker, they are likely to use those tools for multiple projects. This creates a need to continuously look for assistance when using the product and generates a steady amount of traffic to the community. Companies which offer a product which is integrated once and forgotten, such as an API for a finance or travel company, are less likely to see repeat visits to a developer forum, so engagement and response rates among developers will be much lower.

What about Chat-based Developer Communities?

In recent years, some companies have moved their developer community to a real-time chat system, such as those hosted on Slack or Discord. In this model, users join a company-sponsored workspace or server where they can ask for assistance from other users who are online. Docker, Stripe and others offer this as a support option to their developer community. If someone with the right information is online and available to answer, finding support can be quick. Unfortunately, we found in our research that the chances of getting a question answered on a real-time forum was about the same as with real-time forums.

In addition to the uncertainty of getting an answer, there’s also no permanent record of the question and answer, so the exchange really only benefits the person asking, not the 100’s of others who have the same question days and weeks later.

Lastly, developers simply prefer web-based developer forums to chat services. Dan Moore, software developer and author of “Letters to a New Developer,” ran a Twitter survey asking his followers how they prefer to get answers to questions and developers chose web-based forums 2 to 1 over real time chat systems.

As a developer seeking tech help for a platform or software package, which do you prefer? Forums/discourse/async, Slack/discord/sync, Something else

For both web-based forums and real-time chat, a critical mass is required to be successful. Without a large number of users in the forum, the chances that someone with the right set of skills who is motivated to answer a question and is online at the time another user is asking, is quite slim.

To summarize, developer communities can be a productive, low cost support channel for developer tools which have a high degree of reuse. As compared to ticketing systems, answers posted to a web-based forum are available for subsequent users to search through and reuse, further lowering the time and cost to support new users. However, unless your company has a large number of users who repeatedly use your service for multiple projects, don’t expect an engaged community to provide support.

A shift in thinking for a better support experience

With the shortcomings in ticketing systems and developer community forums, it’s clear why developers aren’t getting the support they need to successfully use a technical solution offered by the companies we spoke to. Ticketing systems are too slow to provide assistance and chances are low that an answer will be provided when asking a new question on a developer community platform. So, now that we understand the problems with today’s support solutions, what can be done to help developers be more successful with implementing an API, thus boosting the chances of success of sales deals dependent upon integration? We believe that to make this happen, a shift in thinking is necessary along four key support attributes — access, asking, answers, and assistance. Let’s explore each of these…

Access: Information Should Be Discoverable, not Requested

As seen by the popularity of developer forums for platform products, having a repository of questions and answers in a knowledge base benefits many more users than just the first one who asked. Developers shouldn’t have to go through a gatekeeper to ask their question to find the information they need. Instead, information should be discoverable. Until now, discoverable meant finding the information through search, and indeed, according to research conducted by Elise Hein in her Masters thesis at University College London, search was used by the developers she followed nearly 16 times a day to perform their job, looking for ad hoc how-tos, API references, to recall forgotten details of a specific syntax, learning, troubleshooting errors and looking up official documentation.

However, we see an opportunity to go beyond search and bring those relevant materials into the documentation page so that the right resources are available to the developer at just the right time. When working on troubleshooting an issue, the developer typically goes back to the documentation first to review the syntax and confirm his understanding of how a command or function should be used. If an answer isn’t found there, he’ll then look elsewhere for additional information. “Did someone else encounter the same issue as me? Is there a solution posted?” Instead of requiring the developer to look elsewhere, sudoHERO is embedding the most common knowledge base articles directly in the documentation with insights from other developers about what was most relevant to that part of the documentation. We call this concept Contextual Support.

sudoHERO Contextual Support Widget in action

Asking: Help Developers Ask Questions Intelligently

With new features added, updated languages, frameworks and packages arriving constantly, it’s highly unlikely that all information will be stored in a knowledge base and a stream of new questions must be asked. The current method of asking questions through ticketing systems, chat interfaces, and developer forums make it difficult to ask for and receive additional context in that initial phase of question clarification. If the information needed can’t be discovered in an existing knowledge base of questions and answers, the interface in which to ask should make it easy to share all knowledge necessary to answer the question. Properly formatted code snippets, log files, screencasts to share a process in action, and other formatting should be easy to share. Once engaged with a support rep, users should be able to engage quickly, just as they do with chat-based developer communities, but be able to reference the question and its answer in its entirety for ongoing reference. To solve this issue, we’re building the QuickSolve interface.

sudoHERO QuickSolve, improving the ability to share technical issues.

Answers: Make them Reusable

Developers are familiar with the concept of DRY (Don’t Repeat Yourself)when writing code. In essence, if a bit of code can be reused, move it to a function so it can be utilized again instead of writing it twice. To reduce the amount of time and effort required to support developers, we believe the same principle should be applied to answering support issues. Many users will have the same question, so instead of answering them repeatedly, move them into a knowledge base where they can be accessed, both directly by the developer, by your team, and within the documentation through a contextual support interface. Sometimes the information may come from a web-based forum such as Discourse, a Stack Overflow tag, a GitHub Discussion, a QuickSolve Q&A, or even a blog or YouTube video. The sudoHERO Knowledge Base consolidates all of this information to make it easy for developers to discover either directly from the Knowledge Base UI or within the Contextual Support Widget.

The sudoHERO Knowledge Base, reusable Q&A and other sources of helpful information

Assistance: Extend the Support Team

Lastly, not every company offering an API will have the resources to answer each and every question about utilizing it. With technology stacks much more diverse today than they were just 10 years ago, it’s impossible to stay on top of all the ways a technical product might be integrated into a solution. Companies which produce a platform with a high degree of re-use such as developer tools, can rely upon a community of developers to answer many of the questions their users have, but those companies which produce industry-specific solutions with low re-use, like those we interviewed in FinTech, Travel, and Retail, will find it hard to build a community of developers to provide support. As an alternative, companies should consider extending their core developer support engineering teams with a network of freelance developers who are certified against the product to answer a broad range of edge case questions as they arise. To solve this problem, sudoHERO is building a Developer Support Engineer Network, a pool of highly qualified developers, to assist your company with providing support for your solution.

The sudoHERO Developer Support Expert Pool, on-demand, high-quality and specialized experts to extend the support team.

Putting it all Together

By making access to support materials discoverable, helping developers to ask questions intelligently, reusing those answers and other information, and extending the development team, companies offering an API can provide a much better support experience, increasing the chances that their customers will adopt the solution quickly, reducing the burden on the core engineering team, and boosting revenue from deals powered by those integrations.

The sudoHERO support solution for companies offering technical products

Does your company offer a technical product which requires integration or configuration? Do you offer an API and see similar issues? Are you looking for ways to accelerate the onboarding of your customers and partners? If so, please reach out. We’re rolling out pilots of our service now and interested to see how we can help you meet your goals