Enabling Efficient Access To Relevant Content In API Documentation

The design of API Docs impacts the accessibility of information devs need

Photo: Mikhail Nilov

The design and presentation of Application Programming Interface documentation (API Docs) can pose obstacles for software developers when they try to use a new API. Creators of API Docs can improve the utility of documentation by following this advice from researchers examining how devs use API documentation.

Streamline access to pertinent information

Content organization

Arrange, structure, and format content based on categories that align with the functionality or content domain of the API rather than relying on categories that indicate the type of information presented.

⦾ Advice: Instead of copying the organizational structure and category labeling schemes many API documentation collections use — Samples, Concepts, API Reference, and Recipes, consider using categories with clear lables such as Shipment Handling, Address Handling, etc.

This guideline is an application of minimalist documentation.

Integrate conceptual information with associated tasks

Developers differ in how, whether, and when they use conceptual overviews, which systematically introduce crucial API concepts. Some devs rely on documentation to explain concepts, while others ignore conceptual overviews.

⦾ Advice: To reach each group of developers, don’t segregate conceptual content in a section dedicated to demystifying concepts. Instead, consider presenting conceptual information alongside the tasks or scenarios where knowledge of relevant concepts is needed.

Offer straightforward navigation and helpful search

The navigation should provide devs with clear indications of their location within the documentation and offer unambiguous cues about the context of the topic they’re exploring.

A powerful search that displays related content alongside query results is one of the best ways to ensure developers can locate the information they need. Search should be capable of traversing your content repositories and presenting a unified result that displays all related, relevant content.

⦾ Advice: If unable to provide top-notch search, consider presenting a version of the documentation that exists on a single page, instead of distributing the content across multiple, linked pages. Presenting docs on a single page allows devs to use command—F to trigger the on-page keyword search, a tool many software developers rely upon heavily.

Simplify the process of accessing the API

Understanding entry points is crucial for developer success when working with a new API. Entry points are where devs initially start to begin utilizing APIs effectively.

Provide clean, working code samples

The navigation should provide devs with clear indications of their location within the documentation and offer unambiguous cues about the context of the topic they’re exploring.

Developers rely on — and reuse — code samples in API documentation. Efficient code reuse relies on a clean sample (correct, clear, concise, maintainable, and easy to comprehend) devoid of extra, irrelevant, or invisible code introduced unintentionally while copying the code from its source. Some devs use examples as a starting point when working to solve an API implementation challenge.

⦾ Advice: Generate concise and readily usable code samples (complete and ready to be copied and pasted) that effectively showcase the intended usage of the API.
If using placeholders (referencing other code examples) to eliminate redundancy, reccognize that this approach may make it impossible for devs to reuse code via copy and paste quickly.

Provide relevant background knowledge

The importance of background knowledge in the initial learning process is well understood. Knowledge plays the most significant role in comprehension. It’s like mental velcro.

Relevant knowledge gives words places to stick and make sense, supporting understanding and propelling the reading process forward. The more a dev knows about a topic, the more likely they are to successfully comprehend information about it, compared to those devs with less experience.

⦾ Advice: API documentation should furnish background knowledge to aid developers without domain experience in putting an API to work. Like conceptual information, domain-specific background knowledge should be available when needed and seamlessly integrated with task descriptions and relevant usage scenarios.

Links concepts and their practical use in code

Devs must be able to determine how certain concepts correspond to elements within code. The presence of code elements embedded in API Docs that explain their purposes, usages, and mutual connections with others

⦾ Advice: When presenting conceptual information, utilize code examples that highlight and conceptualize connected elements in the code.

Photo: Sora Shimazaki

Support diverse development approaches

API documentation must accommodate the varying strategies developers employ when approaching a new API. Both the content and its presentation should cater to the needs of both opportunistic and systematic developers.

Devs with an opportunistic learning approach work intuitively and do not follow the processes and suggestions described in the [API] documentation. Instead, they access the documentation only to identify and copy a snippet of sample code, which they modify or extend.

Make it easy for devs to find, copy, and use code

⦾ Advice: Enrich documentation with clean code samples that are complete and comprehensive. Ensure code is clearly delinated from text, making it easier for devs to spot and copy code snippets. Consider using a table with a separate column in which to display code examples.

Indicate the difference between text and code

⦾ Advice: To enhance clarity and improve comprehension of API Docs, signaling techniques like color-coding should be utilized to emphasize code elements within the text and in code examples.

Integrate and reuse important information

⦾ Advice: To ensure understanding, present conceptual information redundantly. Integrate vital details into the text describing how to perform a task with the API. Incorporate concepts into the source code using code comments, helping to guarantee that even opportunistic developers, who may skip the text and focus on the code, will encounter and notice the necessary detail.

Make it easy and fast to put the API to work

⦾ Advice: Usually, developers who follow an opportunistic strategy aim to start their first task quickly. On the other hand, systematic developers tend to take their time to understand the API and then try out sample calls. To help both types of developers, use a documentation approach that focuses on action and simplicity, following the principles of minimalism.