Last week at [APIStrat Chicago](www.apistrategyconference.com/2014Chicago/ APIStrat Chicago), I gave a new and improved version of my Hierarchy of Developer Needs keynote that I initially debuted at [Glue Conference](http://gluecon.com Glue Conference) in May. That first version of the talk and blog entry addressed primarily how to go about identifying your developer and constructing your hierarchy. However, in this version, I dove into what can go wrong with your hierarchy, and how you can go about correcting problems that might arise. It’s a hard subject, because no one wants to admit that their efforts haven’t worked, or that they’ve actively harmed adoption of their API. This fear of failure can actually facilitate the decline of an API simply by failing to act.

It’s all very meta.

Signs and symptoms of a problem

[Alex Williams](https://twitter.com/alexwilliams Alex Williams) asked: What are the warning signs of a problematic community?

It’s an excellent question. Are there metrics that we can put out there that can act as a distant early warning for an unhealthy community or hierarchy that misses the mark? The answer to that is just as complex as creating your hierarchy in the first place.

The signs and symptoms of a problem depend on so many factors:

  • New or existing platform
  • Type of API
  • Priorities of your company
  • Established or new problem space

and the list goes on and on. What may appear as a problem for one API provider could indicate a thriving community for another. Communities are complex organisms, and attempting to label one as functional or dysfunctional without a thorough understanding of it will likely miss the mark.

However, you can make your life easier with a little bit of forethought. Set goals for your developer experience before major efforts or changes (yes, this means technical and non-technical changes). It may sound obvious, but it’s impossible to measure the effects of changes if you don’t have a good grasp of the state of your community beforehand.

What you measure is going to depend on your goals and the community around your API. Is your developer community particularly chatty? Do they file lots of bugs and feature requests? If that suddenly drops off after an API change, or the deprecation of supporting libraries, you might be facing a problem.

Again, if this sounds obvious, that’s because it is. Obvious doesn’t mean easy.

The whys of a dysfunctional hierarchy

Once you’ve determined that there’s a problem with your hierarchy, you can start to diagnose it. Your issue may be fairly straightforward, such as a problem with the resources you provide, or it may be several issues conspiring to give you grief. There are two common(ish) problems that I’ll address here:

  • Mismatched expectations of who is using your API
  • Disconnect with the needs of your community

If you’ve neglected the research part of crafting your developer experience, you may have no real idea of who is using your API. You know your target audience, but you don’t know if you’ve taken the right approach. The good news is that it’s not too late to do research – it’s never too late to do research! Interview the people using your API; collect hard data.

The hierarchy that you’ve constructed may make sense to you, and you probably think that it perfectly supports the developers who will want to work with your API. It’s the classic (and understandable) mistake of speaking for your developer community. Like I’ve said previously, this mistake comes from a good place – empathy and identification – but is ultimately harmful.

Listen to your developers to find out who they are, what they need, and what problems they are trying to solve. It’s a much more effective use of time (yours and theirs) than trying to convince them that your way of development is superior.

Failure versus opportunity

Creative Commons image courtesy of Arne Hendriks

It’s easy to beat yourself up if your initial approach doesn’t work, or if reworked tooling and resources didn’t resonate with your community. The good news is that by recognizing it, you’re actually in a really good place. You can use it as an excuse to renew your contact with your developers, refresh your own technical skills, or take a critical glance at your platform.

What about if you find yourself in the position where, for whatever reason, your API is being used by an unanticipated audience? You could consider this a failure, citing lack of adoption by your target audience, and working hastily to revise your hierarchy. Or, you could see this as an opportunity, recognizing how you’re satisfying an unforeseen need. All of a sudden, your potential community has expanded and your story has gotten that much stronger.

It’s a tool, not a template

Turns out, this entry echoes much of the same message as the last one. There’s no silver bullet, it’s about listening, failure isn’t a sign of defeat. Framing your developer experience in the context of a hierarchy of needs can help you drive the conversation, but it’s a tool and nothing more. You’ll have to calibrate it, service it regularly, and eventually replace it with a newer model…but the investment is well worth it.

Slides:

Hierarchy of Developer Needs – adapting when things go wrong on SpeakerDeck