I published my first API around 1988 for a peripheral to the IBM PC in which the API consisted of software interrupts to MS-DOS. (A software interrupt is similar in function to a procedure call, but used for operating system and device driver functions. I didn’t write the documentation (at least not the published version), but a couple of co-workers and I wrote the interface.
Later, I want to say in 1997-ish, I wrote the API provided by the Performance Data Helper (PDH) dynamic link library (DLL) that shipped in Microsoft Windows NT 4.0 (IIRC). I didn’t write the documentation for this API either as I was still developing software at the time. A super technical writer did the heavy lifting of making sense out of the functions the PDH.DLL provided.
While this isn’t a particularly impressive resume of API development, it shows that APIs and I go way back. They are a very useful tool for solving many problems. Yet, over the past 30+ years that I’ve been using, developing, and documenting APIs, there hasn’t really been much written about their documentation–until recently.
In my informal count (i.e. what I could find on Google while having my morning coffee a few days ago). I came across 17 articles and blog posts on the topic in just the past seven years (full list at the end of the post).
For the curious, here is some of the research that supports what I’ve read in some of these articles.
It’s not really a surprise that APIs are getting more attention lately–their popularity and notoriety have soared in recent years; however, as with so much in technical writing lore, some of what’s been written is based on research, some on personal and anecdotal experience, and much on hearsay (when someone quotes or references someone else’s personal, anecdotal experience).
In Academic paper references, I list the API documentation-related references that I’ve cited in my publications over the years. The good news is that there is now quite a collection of academic research out there, and the better news is there have been many new studies on the topic in recent years (which reminds me, I need to update that list). This is in stark contrast to 2008, when I was getting started in researching API documentation seriously. At that time the list of API documentation-related studies would literally fit in one hand (as in one per finger).
Here are some of the studies I’ve reviewed on the subject, organized by theme in a sort of annotated bibliography.
API reference topic content
The study in a recent article, API documentation – What software engineers can teach us, is very similar in methods and findings to a study conducted at Microsoft by an academic and a Microsoft researcher in 2008 and published in 2009 with a longer version published in 2011.
- Robillard, M. P. (2009). What makes apis hard to learn? answers from developers. Software, IEEE, 26(6), 27–34.
- Robillard, M. P., & DeLine, R. (2011). A field study of API learning obstacles. Empirical Software Engineering, 16(6), 703–732.
A related study, though with a slightly different focus was published a few years later, as well.
- Maalej, W., & Robillard, M. P. (2013). Patterns of Knowledge in API Reference Documentation. IEEE Transactions on Software Engineering, 39(9),
The reason I remember those was because they took a critical (and unflattering) position towards API documentation (which, at the time, I was writing a lot of, so I was probably a little sensitive to the topic). Honestly, the studies were fair and reasonable, however another related article from around that time took a more provocative tone:
- Parnin, C. (2013, March 4). API Documentation – Why it sucks [blog]. Retrieved November 2, 2014, from http://blog.ninlabs.com/2013/03/api-documentation/
As a practitioner at the time, it was frustrating to hear, in scientific detail, how API documentation (like what I was writing) presented all manner of learning obstacles to developers, while seeing, first-hand, that many of the problems cited in those articles could be solved easily and quickly just by adding a few (hundred) more technical writers to the job. My thought at the time was, “So, what’s the big deal? You just discovered that technical writing is understaffed.”
What I felt was missing from those articles, as a practitioner, was the context to know, working with the assumption that the writing will be severely under-resourced, how much of what to write in any particular circumstance. This inspired my Audience-Market-Product thread and later webinar.
API usability
Ten years ago, as a technical writer tasked with documenting hundreds (ultimately, thousands) of interfaces and methods, I noticed how the same amount of documentation seemed overkill in some cases and woefully insufficient in others. It was then I learned about the notion of API usability. I used my yarn example to explain it:
To warm your hands, a ball of yarn and a pair of knitting needles need much more documentation than a pair of gloves made from the same yarn.
Some API methods and interfaces were, essentially, what a ball of yarn would look like if it were implemented in C#, while others were as easy to use as a pair of gloves. Likewise, the audience’s skill and knowledge is critical to how much you document and about what. You wouldn’t, for example, describe the step-by-step process of knitting to an expert, you would cover it at a higher level of abstraction by referring to specific stitch styles.
It turns out, I wasn’t the first to realize this–some of those who got there before me, include:
-
Bloch, J. (2006). How to design a good API and why it matters. In Companion to the 21st ACM SIGPLAN symposium on Object-oriented programming systems, languages, and applications (pp. 506–507). ACM.
- Clarke, S. (2005). Describing and measuring API usability with the cognitive dimensions. Presented at the Cognitive Dimensions of Notations 10th Anniversary Workshop, Citeseer.
- Cwalina, K., & Abrams, B. (2008). Framework design guidelines: conventions, idioms, and patterns for reusable. net libraries. Addison-Wesley Professional.
- Henning, M. (2007). API design matters. Queue, 5(4), 24–36.
API usability as a topic in the press comes and goes (mostly goes), but in 2005 it was all the rage (-ish). Nowadays, I hear, it’s just “good practice.” Good practice, agreed, but not practiced consistently. In any case,
Any API documentation advice or guidelines that don’t take the API’s usability into account are going to be as comfortable to use as shoes you buy without taking the size of your foot into account.
The next time you tackle documenting an API, consider if it’s a ball of yarn or a pair of gloves.
Software developer personas
The developer personas, such as those mentioned in API documentation – What software engineers can teach us, were identified by a Microsoft researcher in 2004.
-
Clarke, S. (2004, May 1). Measuring API Usability. Retrieved December 13, 2016, from http://www.drdobbs.com/windows/measuring-api-usability/184405654
-
Clarke, S. (2007, February 7). What is an End User Software Engineer? [InProceedings]. Retrieved October 26, 2014, from http://drops.dagstuhl.de/opus/volltexte/2007/1080/
Clarke wrote many other related blog posts and articles during the 2004-5 time frame. At the time, Microsoft was doing a lot of research into API usability while the .NET Framework was growing thousands of new interfaces and methods each month.
I talked with Steven after reading his articles and he told me that those personas didn’t really represent people, per se, as much as how developers might approach a problem. The same person could, for example, be a detail-oriented, systematic developer on one problem (say, for example, while researching an API to use in a system design) and, at the same time, be a quick-and-dirty, opportunistic developer while writing some code to test it. (Personas described in: Clarke, S. (2007, February 7). What is an End User Software Engineer? [InProceedings]. Retrieved October 26, 2014, from http://drops.dagstuhl.de/opus/volltexte/2007/1080/)
Developer use cases
There was a flurry of research around 2008-9 into how software developers used documentation. My favorite article about this to cite is:
- Brandt, J., Guo, P. J., Lewenstein, J., Dontcheva, M., & Klemmer, S. R. (2009). Two studies of opportunistic programming: interleaving web foraging, learning, and writing code (pp. 1589–1598). Presented at the Proceedings of the SIGCHI.
Specifically,
“Several participants reported using the Web as an alternative to memorizing routinely-used snippets of code.”
If you can’t do your own user research and can only read one article, I would recommend this one as the one to read–it’s not very long and has some interesting visualizations of their data. At the same time, I would also recommend that you always read more than one study about any subject. So, here are some more on this subject:
- Brandt, J., Dontcheva, M., Weskamp, M., & Klemmer, S. R. (2010). Example-centric programming: integrating web search into the development environment (pp. 513–522). Presented at the Proceedings of the SIGCHI Conference on Human Factors in Computing Systems, ACM.
- Brandt, J., Guo, P. J., Lewenstein, J., & Klemmer, S. R. (2008). Opportunistic programming: How rapid ideation and prototyping occur in practice (pp. 1–5). Presented at the Proceedings of the 4th international workshop on End-user
- Ko, A. J., Myers, B. A., Coblenz, M. J., & Aung, H. H. (2006). An exploratory study of how developers seek, relate, and collect relevant information during software maintenance tasks. Software Engineering, IEEE Transactions on, 32(12), 971–987.
- Stylos, J., & Myers, B. A. (2005). How Programmers Use Internet Resources to Aid Programming. Submitted for Publication.
- Stylos, J., & Myers, B. A. (2006). Mica: A web-search tool for finding API components and examples. In Proceedings of the Visual Languages and Human-Centric Computing, 2006. VL/HCC 2006. IEEE Symposium on (pp. 195–202). IEEE.
Why?
After my preliminary research into the TC Myths project and reading some recent articles on API documentation, I’m getting the sense that we (technical writers) have a habit of reinventing and rediscovering the same thing over and over as though we were stuck in some sort of geeky adaptation of Groundhog Day–an observation made 13 years ago (and probably earlier, as well), which refers to the fact that academic journals (such as the one that contains this observation) frequently live behind some rather expensive pay walls and many are written in “academic.” Which is unfortunate.
Those who cannot remember the past are condemned to repeat it.
–George Santyana
However, if technical writers–people who practice a profession that exists to record things for others–cannot record their past in an accessible way, which is most unfortunate. In academia, our writing has to build on past research and theory to both situate a given article and help keep track of the foundations on which a new argument is made. I don’t see that as much, in articles written by professionals. Professional articles seem to focus on the now and the new–without realizing (or without crediting) that what is described is something from a forgotten past (less than 10 years ago, in some cases). Tom Johnson explores the academic-practitioner gap in more detail in his blog post Why is there a divide between academics and practitioners in tech comm?
At the same time, I get it. Sifting through the bucket of academic journals I’ve listed here and the many more I had to read to arrive at this list is (i.e. it was for me) much more work than reading a 1,000-word blog post. For a practitioner, the 1,000-word blog post is probably sufficient–until it isn’t, of course. Unfortunately, it is often hard to tell where the limits are in a 1,000-word blog post. But, the fact that it’s free to access and a tiny fraction of the academic-journal word count give the blog post a tremendous advantage.
Yet, it still seems like there must be a better way.
Recent API Documentation Articles (non academic)
As promised, here are the recent articles on API documentation that I found while having coffee, sorted by date.