Dev Documentation-5 Tips
29 June, 2017

5 mins

5 Tips to Creating Great Developer Guides

What Are 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 five essential steps:

  • Grab the developers’ 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.

5 Tips to Creating Great Developer Guides

1. Grab the Developers’ 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 ensures 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 legalize 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 this 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 is 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.

5. Get Them to Production

Taking a developer’s application to production varies and is 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 on Developer Guides

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 Build Your Own App Marketplace
Developer Experience

How To Build Your Own App Marketplace...

It’s not easy to build your own app marketplace but it has become one of the greatest product strategies out...

Helping Users Discover Great Integrations
Developer Experience

Helping Users Discover Great Integrations...

The number of third-party SaaS platforms has exploded in recent years, with a huge range of companies allowing users to...

App Marketplace UI: Finding the Balance
Developer Experience

App Marketplace UI: Finding the Balance...

A majority of SaaS providers now find that the best route to growth is to facilitate integrations with other SaaS...