User guide topics
Up until this point, we’ve been focusing on the endpoint (or reference) aspect of API documentation. The reference documentation is only one part — granted, a significant one — in API documentation. You also need to create a user guide and tutorials that cover non-reference topics. Reference documentation tends to appeal to more advanced users, while non-reference documentation is used more by newcomers and novices who need the bigger picture and more handholding.
Essential sections in a user guide
Whereas the endpoint documentation explains how to use each of the endpoints, you also need to explain how to use the API overall. There are other sections common to API documentation that you must also include:
- API Overview
- Getting started tutorial
- Authentication and authorization requirements
- Status and error codes
- Rate limiting and thresholds
- Code samples/tutorials
- SDKs and sample apps
- Quick reference guide
- API best practices
Since the content of these sections varies based on your API, it’s not practical to explore each of these sections using the same weather API like we did with the API endpoint reference documentation. Instead, I’ll provide general descriptions and overviews of what these sections contain.
Other tasks and tutorials
Beyond the sections outlined above, you might want to include other tasks and tutorials specific to your API. For example, what do you expect your users to do? What are their real business scenarios for which they’ll use your API? How do you accomplish these tasks?
Sure, there are innumerable ways that users can put together different endpoints for a variety of outcomes. And the permutations of parameters and responses also provide endless combinations. But no doubt there are some core tasks that most developers will use your API to do. For example, with the Twitter API, most people want to do the following:
- Embed a timeline of tweets on a site
- Embed a hashtag of tweets as a stream
- Provide a Tweet This button below posts
- Show the number of times a post has been retweeted
Provide how-to’s or tutorials for these tasks just like you would with any user guide. Seeing the tasks users can do with an API may be a little less familiar because you don’t have a GUI to click through. But the basic concept is the same — find out what tasks users want to do with this product, and document how to do it.
36/101 pages complete. Only 65 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.