Michael Meng - API documentation: Exploring the information needs of software developers

API documentation succeeds or fails less on how much information it contains and more on whether developers can quickly find solutions in the order their questions unfold. Across interviews, a large questionnaire, and an eye-tracking observation study, developers consistently prioritized practical “what can I do?” guidance first, then shifted toward implementation details, code samples, and task-oriented navigation as they worked through real programming problems. The findings matter because they challenge the common assumption that developers primarily want comprehensive conceptual explanations; instead, they want information that matches their immediate workflow and reduces friction when they hit gaps.

When developers approach a new API, the earliest question is overwhelmingly about purpose and capabilities: “What can I do with the API?” In the questionnaire results, this option was the clear top pick for first questions. Second-place answers split between conceptual understanding (like basic API architecture and structure) and getting the API running. By the third question, the balance tilts toward hands-on implementation—developers most often raised “How do I program with the API?” and “How do I implement my special use case?” The pattern suggests two learning modes: some people pursue a conceptual roadmap first, while others move straight to code and samples to start interacting with the API as soon as possible.

Those differences show up again in how developers choose documentation activities. Interview and questionnaire data point to two strategies: a concept-first approach that treats understanding as a prerequisite, and a code-first approach that uses sample code as the primary entry point. Even when developers say they want conceptual material, concept blocks tend to be ignored if presented as a single, isolated chunk. Instead, concepts become useful when distributed through tutorials or embedded within API reference and recipes.

Developers also report that the biggest obstacles are documentation quality problems—especially wrong, incomplete, or incomprehensible content. Structure and navigation emerge as equally critical. In the observation study, eye tracking and screen recordings showed that participants scanned pages rather than reading them line by line, with attention drawn to headings and navigation elements. Roughly half of their time went to documentation pages and half to non-documentation work areas needed to complete tasks (such as consoles or tools). Within documentation, recipes and sample code pages attracted the most attention, while concept sections drew the least.

The study’s controlled setting—developers working on tasks for an e-commerce-related API integration—also revealed that domain knowledge affected speed more than years of programming experience. Developers with relevant e-commerce background completed tasks faster, while those lacking it took longer even if they were experienced programmers. Over time during the one-hour session, documentation usage shifted: early tasks leaned heavily on sample-based templates, but as familiarity grew, the relative importance of the API reference increased.

Taken together, the research points to actionable design principles: make documentation easy to find and easy to understand; ensure navigation is clear and consistent; avoid organizing content strictly by documentation type (concepts vs. samples vs. API reference) and instead organize by problem or task categories; and provide code samples that developers can build on rather than forcing them to start from scratch. The work stops short of claiming “golden rules,” but it offers a data-backed agenda for improving API documentation around real developer information needs.