A Study on How Developers Use API Documentation

Documenting an API (application programming interface) is hard, and there aren't very many technical writers who can do it well. In my last job before joining the TSX, I had to document a Java API. To do it, I had to learn enough Java that I could follow the code and ended up taking an introductory programming course. I didn't learn enough about Java to write any useful code, but I did at least gain some cred with our developers.

ACM's SIGDOC has published a study on how developers use API documention based on a series of tests with developers working to solve problems based on an API. It looks like a solid piece of research and the conclusions that they've come up with make sense. If you're working on API documentation, you will want to read this.

This article contributes the results of an empirical study that examined how developers use documentation when getting into a new API. Our work is driven by the hypothesis that problems with API documentation may in part reflect usability problems, and in particular, that content and structure of the documentation sometimes do not match the expectations and work habits of developers. Consequently, for API documentation to be an effective aid in learning an API, we need to know which general strategies software developers adopt when solving programming tasks, which information they need and which information resources they turn to.

To address these issues, we conducted a study using the observation method.1 We asked developers to solve a series of programming tasks with an API that was unfamiliar to them. We then analyzed which strategies they adopted to solve the tasks, which parts of the API documentation they used, and which design features of the API documentation led to problems. Based on our findings, we propose several design guidelines that can help to make API documentation more effective.

I think the documentation we produced was good, but the company didn't stay in business long enough to really test that theory. We did, at least, follow several of the guidelines mentioned in the article, which was due in a large part to listening to the recommendations of our development team.