This is the blog of Adam Kalsey. Unusual depth and complexity. Rich, full body with a hint of nutty earthiness.
Developer Experience Principle 4: Easy to Get Help
Freshness Warning
This blog post is over 2 years old. It's possible that the information you read below isn't current and the links no longer work.
8 Oct 2020
It should be Easy to Get Help when a developer is stuck or something goes wrong. Few companies release products without some way of getting help when needed. Developer products shouldn’t be either. In some ways, this is the most important principle of developer experience. Your customers will judge your API product by the quality of support they receive more than any other single factor.
Support doesn’t only involve helping when something goes wrong or breaks. For a developer product support also involves on-boarding. Getting the developer over the understanding hump to figure out what the product does. To understand how to make it do the things they need. Often developers will want to explain what they’re going to do and receive confirmation that the API can do this.
To provide this sort of support, you’ll need someone that can talk to developers in their language. Someone that can read the API calls and see what the developer intends to do. That might be you as the creator of the API. It might be a community of other developers. It might be a professional developer support staff.
When building a support team, you’ll need to think differently. Developer support is not the same as other types of product support. With most support, you can hire support people, train them on the product, and put them to work. Developer products need to reverse this. The people providing support need to understand development so they can help debug. It’s easier to train someone for support than it is to train them for development.
Another source of support is to crowd-source it from your community. For many products, if you give the tools and incentives to your developer customers they’ll help each other out. Stack Overflow has made an entire business from peer support of technical topics.
Whatever the support mechanism is, you need to make it clear to developers how they can get support, what sort of support you offer, and how long it will take to get help. "How long" is an under-appreciated nuance for those that have never been developers. With many technology products, it’s not uncommon for several days to elapse before getting a response to your support request. For developers, they’ll likely have moved on if the response takes several hours. A developer with a question is blocked. They can’t move forward without an answer. They’ll get themselves unstuck as fast as they can, even if that means moving to a different API.
You can make it easier for your developers to support themselves. Self-serve support options that developers answer their own questions will reduce the burden on your support staff while increasing developer satisfaction. Putting common error messages or log lines in your documentation allows developers to search for answers. A page of HTTP response codes and their causes for each API call will help a developer understand why they are getting the response they are.
Release notes or a changelog is a great mechanism for self-service support. A detailed, up-to-date changelog can show a developer when you fixed their issue or added the feature they have been waiting for. A less obvious benefit of quality release notes is that the developers can answer the perennial developer support question themselves: "My code stopped working. Did you change something or did I break something?"
A status page for the API also helps answer the "is it you or me" question. The status page needs to be clear and detailed. When API calls are failing, slow, or otherwise not working properly, list exactly which API calls have the problem. It can be scary to show all your problems. But being honest and over-communicating builds trust. A developer with a problem knows that if your status board is green, then the problem is on their end.
The faster you can unblock a stuck developer, the better their experience will be. It is such an effective tool that some companies consider developer support as part of their marketing budget.