I’ve tabulated my entire collection of docs on API docs for your perusing pleasure in my API documentation bibliography. The documents for which I could find links to online copies have links. The rest have restricted access. Fortunately (and somewhat surprisingly) only 14 (12.5%) of the 112 articles I’ve found so far are restricted.
The articles are sorted by year published and title so the most recent publications will appear at the top. I’ll check in every once in a while to see what’s new in the field and update the list as necessary.
I’ve reviewed each of these to varying degrees of detail. Some are, admittedly, very detailed and read like a functional software specification (i.e. as dry as the Atacama), so in those, I read just enough to pull out the classification details.
I didn’t plan this (nor was I expecting it), but the author-affiliations of all these articles break down as:
- 47.3% of the articles were written by academic authors
- 42.0% of the articles were written by industry authors
- 8.9% of the articles were written by a mix (collaboration?) of industry and academic authors
I wasn’t able to determine the affiliation of the remaining two articles in the list.
Of the 70 articles that specified a programming language, 29 of them talked about a Java API and 20 of them talked about a REST API. Windows and .NET were discussed in only eight of the articles that mentioned a specific programming language (I know, Windows isn’t a programming language).
I’ve tried to give a very brief description of the article’s character. Below the author of each entry in the list, I describe:
- The primary audience of the article: CS (computer and software dev), and TC (tech comm).
- The type of article (webpage, conference paper, etc.)
- The primary theme of the article (API design or documentation)
- The type of publication (professional, academic)
- The type of article content: Tutorial, Editorial, Tool/Method, etc.)
- The nature of the API described (if one is described)
- And the authors’ affiliations (industry and/or academic
I added the API design/documentation category because, as I was reviewing the articles, I noticed that some articles were describing something about documentation, like how to create it, how to evaluate it, how it’s used, etc. Others, referred to API documentation in a context of discussing API design.
This is a work in progress and I’ve pulled out more details than I’ve listed, but I’m still in the process of reviewing my classification model and corresponding descriptions and applications of those categories. As with any qualitative categorization, the subjects don’t always fall neatly into the categories I’ve defined so, some might move around as the category definitions are refined. I’ll post more categories as I feel more confident about them.
Enjoy and please tweet some links to related topics that you don’t see listed and @bobwatsonphd me.