We’ve been in the API game for a little while now, and we’ve seen our fair share of compelling developer communities being cultivated. On the flipside, we’ve also seen some epic fails. At our 2016 Platform Summit, Shayne Parmelee, developer experience lead at Shopify, talked about some of his own successes (and failures) during his time with the company.

And that got us thinking. We wanted to see if we could come up with 5 of the most common mistakes made by API developers when they’re trying to build a developer community and/or improve the DX (developer experience) of their product.

We’ve also tried to come up with a few solutions, several of which were inspired by Shayne.

Mistake #1: 1–1 Support Isn’t Realistic

There’s a problem inherent in the development and release of APIs: users are bound to run into problems, even if you provide thorough, easy to understand documentation. That’s just the nature of software development.

The issue here is that, in all likelihood, you don’t have enough developers on your team for them to function as support agents. Unfortunately in some cases, building an API is a project that developers will undertake and then move on from as soon as it’s finished. Any support agents assigned to deal with the aftermath, if indeed there are any at all, may not be familiar with the nuances of the API.

Solution: Push Support To Community

“When helping developers there’s a lot of incomplete information, lack of context, miscommunication…so it’s really difficult to help one person at a time.”

Take Shopify as an example: Shayne’s team of five was responsible for maintaining 80 endpoints, a ton of libraries, and half a dozen SDKs…amounting to a staggering 20 million API actions every hour.

As he says in his talk, “being helpful feels really good” but it’s not scalable to deal with every query that comes in via email. While working at Shopify, he placed more emphasis on referring API consumers to their forums.

This isn’t the silver bullet that many API developers might be hoping for, though. Shayne mentions that, at one point in his tenure, more than half of the posts on the forums were unanswered. Ultimately though, Shopify did see improvements from community-led support and we’ll explain how they got there below.

Mistake #2: If You Build It They Will Come

Imagine building an awesome API, stacked with useful features and then doing absolutely nothing to promote it. As we’ve previously written about, that’s exactly where some API providers fall short, but we’re hoping the majority of you will realize that a lot of effort goes into evangelism, API discovery, and other strategies in order to bring in users.

Same goes for building a developer community: to quote Shayne again, “just because you have a developer community doesn’t mean that people are actually going to participate.” It’s really a chicken and egg scenario; developer communities are at their most useful when they’re already stocked with threads on different problems and issues that cover possible solutions used by other API consumers — this is what makes StackOverflow so powerful.

Solution #2: Be The First To Post

Instead of relying on a community to form out of thin air, the Shopify team began by leading discussion. After they themselves engaged in their forums, they noticed the following improvements:

• 48% activity increase
• +1165 new app developers
• 45% increase in one touch issue resolution
• 10% decrease in overall number of support queries

That last stat is huge, because it demonstrates that nurturing a developer community can and does have an impact not only on activity but offers true returns when looking at things from a cost vs value perspective.

Building a community only works if you’re a constant presence there. The Overwatch forums, where Blizzard VP Jeff Kaplan regularly pops up to answer questions and gather feedback, is a great example of this.

Mistake #3: Community Gamification Is Easy

Let’s have a quick show of hands: how many of the folks reading this are still playing Pokemon Go? If you’re anything like us then you probably downloaded the app, played for a few days and gave up when “the next big thing” came along.

There’s a certain novelty value associated with gamification – Pokemon Go was one of the first to combine this with AR and take it mainstream – but the novelty soon fades away without other perks to back it up. Issuing badges or “Elite” status to power users sounds like a nice idea in theory but it doesn’t add sustainability on its own.

Solution #3: Add Value Through Karma

In the case of this Shopify trial, adding upvotes offered an unexpected advantage: upvotes proved useful in identifying the most “in demand” features and issues.

What it didn’t do, however, was generate any significant increase in user engagement. Back to the drawing board! Adding perks for participation, like discounted access to products or swag, is one way to incentivize engagement but it probably won’t work on its own unless the community is already growing organically.

Not sure what to offer users who contribute a lot? You could take a leaf out of StackExchange’s book by going really meta and asking your community what kinds of community swag they want! Oh, and make sure you get shirts that fit…

Mistake #4: Not Engaging Early Enough

Whatever the size of a business or organization, some people have a tendency to get carried away by their ideas and building before they’ve taken user needs into account. In that situation, the mindset looks like this:

• Build
• Launch
• Tweak

The main issue here is that developers who work like this don’t see any feedback until the beta testing stage or during a soft launch, at which point it may be too late to address serious concerns. As we’ll see below, Shopify was able to expand that mindset in a way that preserved that iterative sensibility while improving products before they were even built, let alone released.

Any API developer knows that it’s far more difficult to tweak a live API or product than it is to iterate while it’s still in development. That’s because as soon as an API goes live, any downtime at all risks disrupting every service that relies on it.

Solution #4: Pre-Empt Issues Before Launches

Shayne talks about his small team packaging upcoming designs in such a way that allowed them to showcase features to API consumers before they were officially released, thus expanding on the mindset above to create a new development process:

• Idea : Generate initial tech design documents.
• Think: Add some context to those documents, make them more digestible, explain motivation, come up with NDAs.
• Explore: Send to a small subset of developers for feedback.

THEN

• Build
• Launch
• Tweak

Look familiar? The above has a lot in common with the lean startup methodology, only with a little more emphasis on including users early in the process.

Taken from TheLeanStartup.com

By engaging with your users early, be that in an established development community or a randomly selected subset of API consumers, you can get their feedback before you spend weeks or months building something with features that nobody actually needs.

Mistake #5: Your Documentation Is Inadequate

We’ve written elsewhere about the process of AND importance of creating effective documentation, but there’s more to that process than just writing useful content. You need to consider things like the following:

• Which, if any, of your documentation is publicly indexed by Google?
• Is your documentation available to anyone or only those using your API?
• Do you provide examples of how your API works in situ?

Ignoring questions like these is almost as bad as writing shoddy or incomplete documentation, because you’re still putting the same amount of effort in as someone who maintains and distributes their documentation effectively but won’t see the same rewards.

Solution #5: Flesh It Out And Add Context etc.

You can boil Shayne’s position about documentation down to the following sentence:

“If things aren’t easy to find, then they might as well not be there.”

He uses the example of a page that’s linked to from a specific page in GitHub receiving 2.5x more traffic than a similar publicly indexed page. That’s a nice reminder that API consumers want to be able to follow a series of logical steps and not have to jump into Google, search for “how to implement xyz API” and trawl through page after page of results.

Final Thoughts

Building and cultivating an engaged developer community isn’t an easy task. But it does offer a number of huge benefits to you and your API:

• Community led support (and easy pickings for future case studies);
• Pre-launch feedback from existing users;
• Folks taking their first steps towards becoming third party evangelists for your API.

Just remember to do your best to circumvent the anti-patterns outlined above and you’ll be on your way towards creating an incredibly valuable tool to have in your API toolbox.