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