Simplifying API documentation for a great first user experience

Abhinav Asthana

April 25, 2016

Introductions to languages or software systems usually start with a “Hello World” exercise but most APIs are reference manuals only useful for experts. The docs are the first step in a beginner’s learning curve. However with API documentation the developer usually sees a long list of API endpoints in one single page that makes it really hard to get started with the API. It is my belief that API documentation should be similar to learning programming – explaining basic concepts with specific examples. As someone builds up their skill levels, they can use code to solve more complex real world problems.

How do you go about building a great first user experience? Being Postman, we’ve been exposed to several ways in which API publishers approached this problem. Below is a list of questions to help you think through the process of making your API simpler to understand and faster to use.

In part 2 of this post, we’ll talk about our approach at Postman to solving some of these problems with examples and a more in-depth analysis of specific documentation.

Step 1. Who is your user?

Users for your API documentation will come from different backgrounds. They might be backend developers, frontend developers, testers or architects. They’ll know different programming languages and different frameworks. Talking in their “language” will help you get your point across. But everyone’s language is different. Navigating the paradox is critical. Having a range of examples in different programming languages is important – don’t assume everyone knows Java and XML.

Step 2. What does your API do?

Is this API itself the product? Or is this a way for consuming/storing information created in your app? Explaining how your API can make someone or something better will help set an anchor point. At this point it is critical to describe what your API does NOT let someone do saving the user a lot of time and frustration.

Step 3. How does one access your API?

This is where a lot of users get stuck. Getting an authorization token easily for the appropriate access level will help someone try out the API quickly. You can do this by generating an access token automatically for a user if he is signed into your developer portal or your website. You can also create a token management interface similar to Github that can provide users with both flexibility and security. You should have a separate section for authorization against production use cases and how to properly secure a service.

Step 4. How can someone quickly use your API?

Draw out common use cases and “Hello MyAPI” samples. You might solve the majority of problems for your first user right here. This might be a basic how-to on getting and fetching data, on combining different end-points or even a cool use case that might be buried inside your reference docs. Knowing your user (See point 1 above) will help a lot.

Step 5. How can someone integrate your API?

Your API will be used with other internal or public APIs. Examples of how to combine your API with other data sources, data elements to look for inside JSON bodies to transfer data, or other common workflows that your users might want to be aware of.

Step 6. What is the extent of your API?

Finally, write reference documentation for your API. API references should describe possible request and response types – not just the most common one. Sample code in the user’s choice of language will help him run the API docs quickly.

Step 7. Where does someone ask for help?

What happens when things don’t work as expected? Where does the user ask for help? Linking to an FAQ, your support channel or your community page will help the user get unstuck faster.

Conclusion

API documentation is a complex undertaking. Thinking about your user’s first experience of your documentation will help them get started faster and your API’s value more apparent. Creating reference documentation is great but there are several components that I encourage you to consider.

References

• Teach Yourself Programming in Ten Years is a great reference that talks about learning by doing
• What to Write says that a well-documented project needs to have different forms of documentation