Docs by Design

As More docs on API docs described, it’s mostly academic authors writing about API docs, but only by a narrow margin. As I was reviewing the articles I found, my impression was that only men were writing about API documentation.

Because impressions can be mistaken, I went through the articles and reviewed all the authors to determine their gender, insofar as I could. Because this information is rarely reported with the articles, I had to do some digging.

Most of my determination of an author’s gender is based on the authors given name; however, where available, I used their portrait or other references to confirm. For the names that had a recognizable (to me) gender preference, I assigned them accordingly. For those I couldn’t easily tell, I searched for the author’s profile on Google Scholar, ResearchGate, and just plain-ole’ Google to find a social media page. However, after all that, I could not make a credible determination for a little over 5% of the authors so they show up as unknown in the pie chart.

It turns out that my bibliography of 112 articles has a total of 203 unique authors; at least 160 (79%) of which seem to be men, while at least 32 (16%) seem to be women. Or, seen another way,

1 author in 6 who has written an article on API documentation is a woman.

That ratio is roughly consistent with the population of software developers reported in surveys such as Women in Software Engineering: The Sobering Stats (1/6) and 2018 Women in Tech Report (1/7).

So, what does this say?

I’m not sure. It seems like a case of: hey, 1 in 6 authors of articles about API documentation is a woman, which is in the same proportion as the software development field. And, hey, only 1 in 6 authors is a woman, which is in the same proportion as the software development field.  Also noteworthy, the earliest article in my list was authored by a woman.

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

Continue reading “More docs on API docs”

I’ve just collected some more articles for my bibliography of API documentation-related articles and the trend I saw earlier this year hasn’t changed much. In all fairness, eight months is probably not enough time to see a change given the pace of academic publishing. I now have 114 articles in my list of API documentation-related topics.

114!

Searching for API DOCUMENTATION produces a lot of hits on actual API documentation (good news: there’s a lot of API Documentation out there!) Searching for Writing API Documentation produces more articles relevant to what I’m looking for. I’ve also merged my academic and non-academic API documentation bibliographic data, so I can compare and contrast them together.

The merged lists have these characteristics:

114 articles! and I know I haven’t found them all, yet.

• 71% (81/114) of the articles are from CS-oriented sources
• 29% (33/114) are from TC-oriented sources
• 81% of the CS-oriented articles are from edited publications (books, journals)
• 27% of the TC-oriented articles are from edited pubs.
• 27% (31/114) of the API documentation articles were published in 2017

So, what does this mean?

Continue reading “More articles on API documentation”

These are some the new articles I found while browsing Google Scholar on the subject of API documentation since my last update on the topic. I found about 20-some new articles since January, which is exciting! Here’s a review of just the ones I’ve had a chance to skim and write up, so far.

This recent trove of documents makes me happy and sad as did the papers I reviewed in an earlier post. These articles contain lots of great research into API documentation, who uses it, and how it’s used. All of these are available for download and I would encourage you to do that if you are interested in API documentation.

At the same time, I’m still disappointed that there has been absolutely zero research published on the topic from the technical communication community this year (was I really the only one who was doing that lately?!) and little to no reference to anything tech-comm related in these papers. If you know of some API research published in a tech-comm venue (and that’s not already in my list), please let me know. At this point, all this is just a warning that some of my disappointment might seep through into my article reviews.

Many of these articles (3/4) had both academic and industry authors, which suggests that industry-academy partnerships aren’t that unusual in the research of API Documentation—if you’re in computer science. In tech comm, as Tom Johnson’s recent survey laments, not so much.

Some of these articles cite earlier research in developer user studies and also contribute to that body of work. None of them, however, cite what I would call writing or reading research. That wouldn’t be so troubling, if it were just these articles, but I can’t think of an article on the topic of API documentation published in a computer science venue that talks about actually reading and using the content. At the same time, there now seems to be a recognizable genre in API documentation literature that Head et al. describes as, “finding anti-patterns in documentation” (see reviews below).

So, here’s a short review of four of the articles I read this morning.

Continue reading “New articles on API documentation”