Developer Experience
29 June, 2017

5 mins

How Great Documentation Improves Your Developer Experience

Offering a rich developer experience is becoming critical to an API provider’s success in building a successful developer community. However, when taking the view that an API is a product merely providing technical documentation, such an API specification and an interactive explorer is not enough. In this post, we look at the importance of subject matter and how it is crucial to giving your developer community the context they need to successfully work with your product
and your API.

The API Economy is a diverse landscape, incorporating a huge number of different products and subjects. This diversity can create an exciting and creative environment for application developers with an endless  number of variations on how APIs can be used. However, and despite their best efforts, they can’t all be experts. To create the right developer experience, you need to provide information on a given subject to send them in the right direction, without which, they risk getting bogged down in detail and jargon they don’t understand.

It’s important to remember that when we create API documentation, the developer community doesn’t necessarily know what we’re thinking. We may understand why a specific part of our implementation is important in the context of an area like health, banking or payments, but our readers may not. When we’re documenting our APIs, the information we convey needs to display three important characteristics:


  • Context: Developer documentation must create context for a developer in describing not just what is important but also why it is important. Simply producing a series of code snippets (in the style of an IBM how-to) with zero explanation, is not enough to help a developer understand what they are reading is important in the context of what they are creating.
  • Applicable: As a complement to providing sufficient context, documentation must also be immediately applicable for a developer. Once they understand why a given aspect of your product is important, they must be able to apply that knowledge in their application with code snippets and examples.
  • Targeted: Subject matter information must also be written so that it is targeted to specific subsets of the community. While the primary audience is likely to be developers, other teams and job roles such as product owners and operators must  be catered to. The documentation provided to them must not muddy the waters for developers. Moreover, there are  subsets amongst developers themselves, with different needs for front-end and back-end developers, for example.

There are  no standards (yet) on how best to approach incorporating these characteristics into what you offer your developer community, so it’s  worth exploring an example what ‘good’ looks like through the lens of


How Stripe Gets it Right

It’s verging on hyperbola, but it’s fair to say that Stripe is taking the world of payment APIs by storm. They provide easy-to-use front-end components, an SDK and an API for accessing a variety of different payment methods and rails. What is interesting from the perspective of subject matter, is how Stripe have tailored and subdivided their documentation, targeting different types of developers with applicable documentation while providing important context throughout.

For example, developers may not be familiar with payment card industry (PCI) regulations, but Stripe aims to bridge the gap by dropping in important information throughout their tutorials and reference documentation. This reduces the need for a developer to read more detail elsewhere. The holy grail for most organizations is staying outside PCI scope and Stripe provides the context of this goal at the point of information delivery. This allows developers to ingest specific detail that helps them be successful  and understand the relevant safeguards for payment card data.

Stripe also aims to target different types of developers with well-organised documentation relevant to both their role and their needs. In doing so, Stripe ensures that developers need only read what is applicable to them. For example, their API documentation is completely separate from front-end components such as Checkout and Elements. The SDK documentation is similarly subdivided between iOS and Android. Information on charging a payment instrument (the step after collecting payment details that actually executes the payment) is even on its own page, so a front-end developer implementing Checkout, does not need to search through changing information, and can focus purely on Checkout itself.

Finally, the code samples provided by Stripe are eminently applicable as their developer documentation is automatically tailored with a developer’s API key (provided the developer is logged into the Stripe site). When a developer wants to execute a cURL command when going through the API documentation, they can do so without any modification.


Final Thoughts

As the Stripe example shows, crafting excellent, informative API documentation is an important affordance to an API provider’s product, by delivering the right information to the right audience. Repeating Stripe’s success means:


  • Remembering that your audience is not uniform and that developers come in many different shapes and sizes. Cater to  them by tailoring your documentation to subsets of skills.
  • Being cognizant that your audience might not be expert in a given subject but that their need for detail is low; what they need is context. Give them the right amount of context so they understand enough about the subject matter, product or industry your API relates to.
  • Making sure what you convey is applicable by giving examples that can be related to and acted upon with minimal effort.

By following these guidelines, you’ll have every chance of creating a well-informed developer community who’ll find your API documentation a joy to work with.

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...