A Field Study of API Learning Obstacles
Reviewed by Jorge Aranda / 2011-11-08
Keywords: Documentation
Robillard2010 Martin P. Robillard and Robert DeLine: "A field study of API learning obstacles". Empirical Software Engineering, 16(6), 2010, 10.1007/s10664-010-9150-8.
Large APIs can be hard to learn, and this can lead to decreased programmer productivity. But what makes APIs hard to learn? We conducted a mixed approach, multi-phased study of the obstacles faced by Microsoft developers learning a wide variety of new APIs. The study involved a combination of surveys and in-person interviews, and collected the opinions and experiences of over 440 professional developers. We found that some of the most severe obstacles faced by developers learning new APIs pertained to the documentation and other learning resources. We report on the obstacles developers face when learning new APIs, with a special focus on obstacles related to API documentation. Our qualitative analysis elicited five important factors to consider when designing API documentation: documentation of intent; code examples; matching APIs with scenarios; penetrability of the API; and format and presentation. We analyzed how these factors can be interpreted to prioritize API documentation development efforts.
Developers don't live on Stack Overflow alone. For many API questions, there are still materials and documentation that can help them speed up their learning process (or there should be, I think, while I try to learn node.js…). Robillard and DeLine's report is full of rich insights and practical implications relevant for anyone trying to improve the developer documentation of their products.