A Taxonomy of Knowledge Types For API Reference Documentation
A Taxonomy of Knowledge Types For API Reference Documentation
A quick review of the 12 types of knowledge commonly found in API Docs
API Documentation has been called “the most severe obstacle“ preventing software developers from quickly putting a new API to work. Developers complain that incomplete, inaccurate, and inconsistent documentation hamper their productivity by interrupting their workflow and causing them to lose focus.
Improving API documentation can reduce disruptions in concentration and help keep devs in the zone.
”Eliminating a one-minute, documentation-induced distraction through improved documentation could save 15 minutes of lost software developer productivity and provide a more satisfying, and more profitable, development experience,” writes Robert Watson, a senior technical writer at Google.
For several decades, the format used to structure and present documentation for application programming interfaces (API Docs) has remained largely unchanged. While research on what developers think should be contained in API Docs has revealed a list of improvement suggestions, few studies have compared what information devs say they need to what information they actually use.
In Patterns of Knowledge in API Reference Documentation, researchers Walid Maalej and Martin P. Robillard, point out that there’s “no standard and a few conventions regarding the content of reference documentation,” calling the typical API reference documentation a “mixed bag of information items.”
There’s been little effort to develop evidence-informed best practices for organizing, categorizing, and structuring dev-focused docs, they say. That needs to change.
Maalej and Robillard evaluated several popular sets of API docs to discover what types of knowledge are commonly available and how that information is categorized (see Figure 1 — “Taxonomy of Knowledge Types for API Documentation”).
Their efforts resulted in the creation of a taxonomy that they say is:
Reliable — the docs are organized to help different API docs users understand the type of information contained in each individual section
Meaningful — the docs contain content of relevance to the task at hand
Fine-grained — the docs provide more than a few high-level categories of knowledge
Figure 1
Source: Patterns of Knowledge in API Reference Documentation (2013) — Waalej and Martin P Robillard (IEEE Transactions on Software Engineering)
⦾ Advice: Consider using the taxonomy in Figure 1 to evaluate the content of your existing docs, better organize them, and to detect and eliminate low-value content like non-information.