While almost everyone seems to agree that documentation is of key importance when launching an API, little is said about how it can actually affect API adoption. Jeffrey Hammond, a Principal Analyst at Forrester, claims that “adoption patterns are shifting towards developers,” giving them the power to “block or aid the adoption of software.” This means that a significant way to persuade decision makers to choose your software over your competitors’ is to gain the trust and confidence of developers.

One of the best ways to increase developers’ awareness of and interest in your product is to make your API as immediately usable as possible. This begins with the documentation.

How Does API Documentation Affect Adoption?

Documentation plays a central role in the way an API is perceived by developers. Poor documentation is often a sign of a badly maintained API — one that developers will try to avoid at all costs. The more you focus your API documentation on the developers, the more it will build their confidence and improve their experience.

Onboarding Experience

Begin with the first impression. It shouldn’t take a developer more than five minutes to understand your API and begin using it. The only way to make this a reality is to provide a streamlined and concise onboarding experience. Documentation should quickly take developers to a stage where they’re already using the API with little or no effort.

One possible way to make this happen is to create a “sandbox environment,” where developers can play with the API without actually hitting your production servers. This allows you to offer a minimum signup process, asking only what is really needed instead of a lengthy registration process that can drive many developers away.

Good documentation should clearly inform developers of what they must do to get started — and how to do it. If your API works with API tokens, generate one on-the-fly and let developers use it right away. If you use OAuth, provide fake consumer information, and even an access token, so developers can start making API calls immediately.

Remember that this is only the first step of engagement, and developers are still evaluating your API. You should let them experiment as much as possible, but without compromising your production systems or any real user information.

The Power to Experiment

To let developers experiment with your API you can follow any or a combination of the following strategies:

1. Offer an API console: This is the minimum you should offer as an experimentation tool. With an API console, developers are encouraged to immediately test what they see in the documentation, and see real API calls taking place.
2. Offer an SDK: Publish an open source SDK in as many programming languages as your target developers use. Provide comprehensive SDK documentation and make it easy to install and configure. Popular ways of distributing SDKs include npm for Node.js, Packagist for PHP, RubyGems for Ruby and PyPI for Python.
3. Publish tutorials: Begin with a Quick Start Guide and follow with tutorials showing them how to implement interesting use cases with your API. Provide sample snippets using the SDKs in as many languages as possible, so that developers can simply copy and paste the code and communicate with your API with minimum effort.

By following this approach you will offer a rich and comprehensive documentation with all the tools that a developer needs to get started immediately. Developers will be able to choose their favorite programming languages and follow your tutorials on how to implement the specific use cases they’re looking for.

Building all this from scratch is no easy task. Documentation is something that needs a lot of focus on detail, and should continually reflect the latest API changes. Our advice is to always follow the industry standards and use proven method and tools.

Tools that Help you Build Great Documentation

Among all the API-related tools, documentation is probably the area showing the most growth. This is particularly interesting because documentation is traditionally something that developers pay little attention to when launching code. There are now several standards and tools that will cut down documentation implementation time dramatically.

Swagger, for instance, is an open source tool chain that lets you easily create interactive documentation. Apigee is using Swagger on its Apigee-127 toolkit. Apigee-127 is a model-first toolkit for building rich, enterprise-class APIs that run on any PaaS provider that supports Node.js. To use the toolkit, you start by modeling your API with a built-in Swagger editor, and from there your API code is automatically generated.

RAML, or RESTful API Modeling Language, is a specification and a set of tools that lets you model your API and provide documentation from it. It has been gaining a lot of adoption in the enterprise space, probably because it follows three main principles: it’s human- readable, simple, and can be broken down by patterns.

With an even more human approach, API Blueprint lets you write your API specification in Markdown and serve it as your documentation. The same Markdown file is also used by a range of tools to generate code, run integration tests and debug the API. The number of ways API Blueprint can be manipulated is impressive as there are more than 15 tools that can convert it into other formats.

Read the docs is a hosted documentation service that lets you write documentation without worrying about hosting it yourself, or maintaining its changes. Without concern for these details you can simply focus on the quality of the documentation. In the end, this is what matters most. In addition, an interesting feature is their webhook support, This feature allows you to easily connect your version-control system (e.g. GitHub), and initiate a documentation update automatically whenever you do a commit.

Conclusion

Since documentation is more and more the main driver for adoption, leading the way for developers to understand and appreciate your API, it should be the most important thing on your agenda. According to numerous authorities in the API space, developers are playing an increasing role in the decision-making process when considering a new product or service.

Documentation is the face of your API and is the first thing developers see when they land on your web site. You should make their experience as smooth as possible and offer an engagement process that can start with an easy and quick onboarding, and drive them into experimenting your API by implementing their preferred use cases. You should consider offering SDKs in popular programming languages, and a range of tutorials and guides to make integration implementation a very smooth ride.

In the end, if developers’ opinion about your API is positive, they will recommend your product over that of the competition. The result is that you will win new customers!

Do you have more ideas or examples of ways to improve API Documentation and increase adoption? If so, share it in a comment here or let us know on Twitter or Facebook!

[Editor’s note: Nordic APIs is an independent publication and has not been authorized, sponsored, or otherwise approved by any company mentioned in this article; however, Apigee has previously been a Nordic APIs event partner.]