Conceptual Topics in Documentation

In learning how to write documentation, such as API documentation, you would encounter “Conceptual Topics.” These include product overviews, quick reference guides, getting started tutorials, and more. Understanding these topics is crucial because it helps you organize the information in your technical documentation. By reading this article, you will learn about these conceptual topics.

Image from freepik

What are Conceptual Topics in Documentation?

Conceptual Topics provide users with a comprehensive understanding of how to use the API (Application Programming Interface). They don’t just serve as mere reference materials; they provide guidance and context for the users to understand and use the API. They include:

• Product Overviews
• Getting Started Tutorials
• Authentication and Authorization
• Status and Error codes
• Rate limiting and Thresholds
• Quick Reference Guides
• Glossaries

Next, let’s discuss these conceptual topics in detail.

Product Overviews

Behind every technical documentation is a need or problem it’s trying to solve. The company behind the documentation has a product or solution to market to its target audience. And they do this by exposing the products via their API. But there’s a roadblock here, which is the target audience understanding the purpose of the API and how it solves their problem. Now, this is where “Product Overviews” come in.

The first thing the users do when they visit the documentation is to understand the API’s purpose and functionality. So, the Product Overview is like the initial point of contact for the users, describing how the API addresses the users’ needs or challenges.

For example, the Squarespace documentation provides a product overview as highlighted below:

From reading the Product API overview of Squarespace, you can tell its purpose and functionality. In addition, the product overview also contains information about the limitations, use cases, and technical requirements.

Getting Started Tutorials

Okay! Now, the users understand the purpose of the API, its functionality, use cases, limitations, and technical requirements, but these are all just theories, right? There’s no action yet. Some of the users will be curious to try the API out quickly. This is where the Getting Started Tutorials come in.

Usually, you’ll have a link to the Getting Started Tutorials page immediately after the Product Overview page. So, what’s the purpose of the Getting Started Tutorials?

It involves several key steps, which include obtaining API keys, setting up a development environment, and making basic API calls. If you’re not a developer, these may sound a bit vague, so let’s go into them a little bit to see what happens in each step:

• Obtaining API keys: API keys are like the secret keys that give you access to an API; you can call them unique identifiers. When a user tries requesting the API, they are required to possess an API key, which grants them access by authenticating their request. Getting an API key depends on the API provider, but we’re not going into that. But usually, you would find information on how to get the API key in the API documentation.
• Setting up a development environment: For users to be able to interact with the API, they would certainly need to set up a development environment, which would involve installing the necessary software and libraries.
• Making basic API calls: Once the users have their API key and development environment set up, the next step is to make basic API calls. Making API calls means sending HTTP requests to the API’s endpoints and handling the responses.

A good example of documentation that includes a Getting Started Tutorial is the Google Maps JavaScript Documentation. It explains the purpose of API keys and how they work in the context of the Google Maps JavaScript API, guides users through the process with step-by-step instructions on how to create an API key, and guides users through the initial steps of setting up their development environment and making basic API calls by explaining how to use the API key in their projects.

With this, developers can quickly get up and running with the Google Maps JavaScript API. Look at how it looks below:

Authentication and Authorization

The companies want to ensure that only legitimate users or applications can access the API or carry out specific actions. They want to protect their data and resources from unauthorized access. Achieving this requires documentation of information about authentication and authorization. What are they?

Authentication is the process of verifying that the requester of the API, whether it be a user or application, is who they claim to be. As discussed earlier, one common method of authentication is through the use of API keys.

This section in the documentation explains how to authenticate requests. For example, in a request made to an API like “https://api.example.com/data?key=YOUR_API_KEY”, the API key is added as a query parameter or can be included in the request header.

Sometimes, authentication may fail due to invalid or expired API keys. This section also covers what error messages to expect in such situations, known as “Error handling.”

Authorization, on the other hand, determines the actions an authenticated user or application is permitted to perform. Users must be authorized or granted permission before accessing specific resources or performing actions within the API. Authorization can be based on different access levels, such as free and pro tiers, each with distinct permissions.

In essence, this section should guide users on handling authorization. It should include information on how users can specify their access level or permissions when making requests, such as adding additional headers or parameters like an access token or a specific flag indicating desired permissions.

Check out the GitHub API documentation to see these in action:

Status and Error codes

The outcome of the API requests made by developers would vary. So, it’s important to provide information about the outcome of the API requests. These include status and error codes. By providing information about the status and error codes, developers can understand whether their requests were successful, how to fix issues, or what went wrong.

What are these status codes? You can call them standard HTTP Status codes. They are predefined codes that indicate the general outcome of an HTTP request. For example, “200 OK” means the request was successful, while “404 Not Found” indicates that the requested resource could not be found. These are just some examples of status codes.

Also, note that API documentation often defines its own status and error codes. This is where custom status and error codes come in. They provide specific feedback to developers. They are called custom because they are unique to the API and can provide detailed information about the request’s outcome. For example, an API might return a custom “429 Too Many Requests” status code when a rate limit has been exceeded.

To see an example of documentation with well-documented status and error codes, check out the Mailchimp API documentation:

Rate limiting and Thresholds

Companies or API providers worry about the reliability and performance of the API and ensuring that DoS (Denial of Service) attacks are prevented. They do this by limiting the number of requests a user or application can make to the API within a certain timeframe. This process is called “rate limiting”. It ensures that all users get a fair usage of the API and protects the API from abuse or overuse. It also saves the cost of transmitting data and maintaining servers.

So, this section of the documentation provides information about how the limits are enforced and how users can manage their usage to avoid being blocked.

For example, GitHub’s API Documentation provides rate limits for unauthenticated requests, authenticated requests, and requests made using OAuth tokens. The unauthenticated requests are limited to 60 per hour, while authenticated requests have higher limits depending on the type of token used. This is how the rate limit section looks:

Quick Reference Guides

Some users are experienced and wouldn’t want to go through the detailed documentation to find what they are looking for. These users would prefer quickly looking up an accessible resource in the documentation that they can read or glance through to understand the API’s structure, endpoints, parameters, and responses. This accessible resource is called the “Quick Reference Guides” because it concisely summarizes the API’s endpoints, parameters, and responses.

Check out Stripe API documentation. It has a user-friendly Quick Reference Guide, as shown below:

Glossaries

Many terminologies will be used throughout the documentation, and some of these terms may be difficult for users, especially those new to the technology, to understand. To ensure that every user can understand the technical terms and concepts, including a “Glossary” section is important. In other words, the Glossary is a comprehensive resource that defines technical terms and concepts used throughout the documentation.

For example, the documentation for Apigee includes a great Glossary section, as shown below:

What’s more?

You’ve learned so far about the conceptual topics with real-world examples. Another section that can fall under the conceptual topics is “Best Practices.” This section provides recommendations on better API use, including handling errors and optimizing performance. This section aims to help the users avoid common pitfalls and follow recommended patterns for using the API.

Review the Documentation samples mentioned in this article to become more familiar with how these conceptual topics are written!