Studying the Documentation of an API for Enterprise Service-Oriented Architecture
Brad A. Myers, Sae Young Jeong, Yingyu Xie, Jack Beaton, Jeff Stylos, Ralf Ehret, Jan Karstens, Arkın Efeoğlu, Daniela K. Busse · Journal of Organizational and End User Computing · 2010
All software today is written using application programming interfaces (APIs). We performed a user study of the online documentation of a large and complex API for Enterprise Service-Oriented Architecture (eSOA), which identified many issues and recommendations for making API documentation easier to use. eSOA is an appropriate testbed because the target users include high-level business experts who do not have significant programming expertise and thus can be classified as “end-user developers.” Our study showed that the participants’ background influenced how they navigated the documentation. Lack of familiarity with business terminology was a barrier for developers without business application experience. Both groups avoided areas of the documentation that had an inconsistent visual design. A new design for the documentation that supports flexible navigation strategies seems to be required to support the wide range of users for eSOA. This paper summarizes our study and provides recommendations for future documentation for APIs.