User guide topics
If you're an engineer, please take this quick survey focused on engineers who write documentation. This will help me better understand trends in this space. You can see the ongoing results here.
Up until this point, we’ve mostly been focusing on the reference aspects of API documentation (the endpoints). The reference documentation is only one aspect of API documentation. In this section, I’ll cover the main non-reference topics that are commonly found in API documentation. Rather than “non-reference topics,” you might consider this type of information the “user guide.”
Common topics in the user guide
The following are non-reference topics commonly found in API documentation:
- API Overview
- Getting started tutorial
- Authentication and authorization requirements
- Status and error codes
- Rate limiting and thresholds
- Code samples and tutorials
- SDKs and sample apps
- Quick reference guide
- API Glossary
- API best practices
Beyond the sections outlined above, you might want to include other tasks and tutorials specific to your API, based on what you expect your users to do and the business scenarios for which they’ll use your API.
In each non-reference topic, I’ll provide general descriptions and overviews of what these sections contain, followed by examples from actual API documentation sites.
With each topic, there’s an activity for you to go into your open-source project and evaluate the non-reference topic at hand. Although many of the concepts in the non-reference section are basic, when you look at the information in context, that is, when you look to see how the information is actually implemented, it gets a lot more interesting.
61/110 pages complete. Only 49 more pages to go.
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.