5 Steps to Creating Great Developer Guides

Great developer guides are at the heart of a compelling API proposition. They allow your target audience to act quickly on the knowledge they need to start developing against your API. Creating a great developer guide involves 5 essential steps:

  • Grab the developer’s attention
  • Keep them interested
  • Nod to the legal stuff
  • Deepen their knowledge
  • Get them to production

It goes without saying that developer guides are critical to the success of an API. While there is no magic formula for creating a guide that hits the mark with your developers, there are some common themes that surface. In this post we look at how to successfully complete each of these steps to create a developer guide that really excites and compels your audience to use your API.

1. Grab the Developer’s Attention

Developers are first and foremost techies who appreciate code, toys and cool tech. However, they also appreciate getting their job done with minimal fuss. Grabbing a developer’s attention in a developer guide means showing them something they can instantly act upon – spend too long dwelling on subject matter or intricate detail and you’ll have lost them.

There are all sorts of ways to accomplish this but an example that stands out is the bank transfer API Dwolla. Dwolla ensure that developers are placed front and center by instantly making usable code snippets available to them in a variety of popular languages. Developers need only grab the dependencies and copy-and-paste to get an integration with the Dwolla API running.

2. Keep Them Interested

Once you’ve grabbed a developer’s attention you need to keep them interested through easy to use guides and utilities that let them progress from a simple code snippet to a running application. There are many ways this can be accomplished but again Dwolla shows how this can be done quickly and effectively.

From the main page a developer can access tailored and more detailed documentation. Like the front page a developer can select one of the available languages and the code snippets are then shown in that language. Developers can also self-provision a sandbox which simplifies the setup of their development environment. Dwolla ensures that the guides and sandbox setup are so easy to use that a developer will not lose focus.

3. Nod to the Legal Stuff

With usable code snippets and a running application a developer is well on the way to becoming part of your community. However, and like it or not, you will need to subject your developer to “legaleze” at some point during your developer guide. Failing to point out the terms and conditions – and a developer or their organization failing to heed them – can be disastrous. This is especially true if awareness comes further down the line when significant terms of use are discovered that stop them using your API.

The best advice is to link the developer guide to a policy for your API that is big, bold and brash. It should be written in words that contain as few syllables as possible and detail the policy in no uncertain terms. Taking the approach will at the very least alert developers to potential pitfalls in how they use your API or raise their awareness enough to seek consultation with your legal team.

Instagram is the poster child for this approach and implement a platform policy that outlines exactly what an API consumer can and cannot do. Instagram are well known for developer application takedowns which makes their policy even more difficult to ignore.

4. Deepen Their Knowledge

An interested and motivated developer who knows what they can do with your API is ready to take the next step by deepening their knowledge. This can cover a range of subjects, including (but not restricted to):

  • Understanding the “unhappy” path including error scenarios that happen out-of-band of the API call and how these are addressed.
  • Using web hooks to create feedback loops for other out-of-band activities.
  • Understanding rate limits, quotas, throttling, etc. that may affect how your API can be consumed.

Deepening a developer’s knowledge is not, however restricted to educating developers on technology matters. They might need to understand the subject matter of the industry you operate in as your implementation might reflect certain industry practices or constraints. Your API may also be “less than perfect” and coupled to an existing backend that is not RESTful in nature. Your maturity level in delivering APIs might also still be growing, meaning some design choices need explaining.

Deepening a developer’s knowledge therefore gives them the background they need to successfully complete their integration with your API. The final step is to take their application to production.

5. Get Them to Production

Taking a developer’s application to production varies hugely dependent on the API provider and the type of API. The key to success is obviously making this process as easy as possible, with clear guidelines on the steps and process.

For free to use public APIs that implement no security measures getting to production can be straightforward. Most consumers are likely to be using a single API endpoint right through the entire API lifecycle. API providers should ensure developers are aware of this fact to allow them to develop their application as efficiently as possible.

Where an API does have a promotional model the API provider needs to clearly state how developers will need to configure their applications between “development” and production. For example Stripe provides clear guidelines on the scope and use of the API keys they provide.

A number of API providers such as Facebook and Instagram also require applications to go through a review process before they can be “promoted” to production. Both Facebook and Instagram supply detailed guides on the review process and allow it to be triggered from their developer portals.

Final Thoughts

The key to a great developer guide is getting a developer from zero to production with as few hurdles as possible. Where hurdles are necessary, make sure they are the right size and that the developer knows how to get over them. By keeping developers interested and engaged with a great developer guide you have every chance of building a thriving audience for your API.

Related posts

How to Reject Apps the Right Way on Your App Marketplace
Developer Experience

How to Reject Apps the Right Way on Your App ...

While you generally want to encourage as many app submissions as possible, it’s essential that you hold developer’s submissions to...

Balancing Business and Tech as an API Product Manager. Part 1: Developer Experience
Developer Experience

Balancing Business and Tech as an API Product...

API product managers are the Janus of the API world. They have multiple faces, looking to both the business and...

How Great Documentation Improves Your Developer Experience
Developer Experience

How Great Documentation Improves Your Develop...

Offering a rich developer experience is becoming critical to an API provider’s success in building a successful developer community. However...