Posted on by bobw

API documentation research-Where’s Tech Comm?

Google Scholar was reading my mind this morning and provided me a list of recommended papers. This was both interesting and troubling at the same time. It was interesting that they knew what I’d find interesting (they have been listening!) and troubling that I was only familiar with a couple from the list (i.e. I need to read more, apparently). Most disturbing was that in the articles on API documentation, most all references that those articles cited were from computer science literature and not from documentation or technical writing. One article cited my dissertation, so I can’t say there were no references to documentation research.

It could be there’s nothing to find. Searching Google Scholar for articles on “API documentation” yields no articles from non computer-science journals until one of mine appears on the fourth page of search results. So, it’s a reasonable question to ask if there are other sources to find.

In any case, here’s what I’ve found, so far.

Articles reviewed (during my lunch break)

As I said, I only recognized one of the papers in the list, and I’ve not reviewed every single one, yet, so I’m still pulling this together.  Here are the articles that I’ve reviewed, so far.

Preliminary Analysis of REST API Style Guidelines

I thought for sure that a study of API documentation would reference some work on actual documentation, but nope. To their credit, this is a great resource for technical writing geeks (like yours truly) in that they list 32 different API style guides–with URLs.  (I had no idea that there were 32!) The article provides a good breakdown of the information that the different style guides recommend, so if you’re curious to see what other people are including in their API docs, here’s a good place to start. I’d also never heard of the conference at which this paper was presented: PLATEAU 2017  for “The 8th Workshop on Evaluation and Usability of Programming Languages and Tools.” I guess I need to get out more.

Automated Example Oriented REST API Documentation at Cisco

Another article about API documentation that cites only Computer Science articles. The article describes how Cisco is automating their documentation so <sarcasm> I suppose there’s no reason to consider what technical writers might have to say on the subject </sarcasm>, but then again, perhaps they haven’t been considered because they haven’t said much [that’s findable] on the subject?

A systematic approach to API usability: Taxonomy-derived criteria and a case study

This was interesting in that I haven’t seen API usability talked about much lately. The article proposes an API usability taxonomy that is comprehensive, however from the surface, doesn’t seem to solve the problem that Clarke’s model presented–that of having so many categories that it was hard for anyone but the most dedicated to apply or understand. Nevertheless, it was refreshing to see that it is still something people are talking about in that it has a direct application in API documentation.

Application Programming Interface Documentation: What Do Software Developers Want?

This has been out for a while, now and is the only one I recognized. I talk about it in my post on A Brief History of API docs. It is one of the few on the list that references a tech comm article.

Docio: Documenting API Input/Output Examples

This was the most disappointing article I found. Not that the article is bad, but of all the new titles I found, this seemed like the most likely to link up to an API documentation topic from a tech comm author. But, nope. No such luck.

What does it mean?

In reviewing the above subset of this month’s recommendations, I have mixed feelings.

The good news

  1. People are talking about API documentation with the intent of improving its production and consumption.
  2. Researchers are receiving grant funding to research it.

As an academic with an interest in the subject, both of these are exciting (and I’ll have to dig into the grants that funded their research…)

The bad news

  1. These conversations are taking place without any reference to tech comm research, which seems incomplete
  2. A recurring theme is more on how to automate the creation of API documentation or a focus on those parts that are more easily automated and not much perspective on the genre as a whole.

These are both disturbing for me as an academic and for what this holds for tech comm. I mentioned some of this in my post titled, Is writing API documentation going the way of the keypunch operator? While I’m all for automating what can be automated, I think that such a topic should be considered in a larger context. This reinforces the points I made in the implications I raised in Is writing API documentation going the way of the keypunch operator?

Tech comm is going to have to step up and become more visible in this discussion or be left out and left behind.

This month’s recommendations from Google Scholar

Leave a Reply