Improving Documentation for eSOA APIs through User Studies

  • Authors:
  • Sae Young Jeong;Yingyu Xie;Jack Beaton;Brad A. Myers;Jeff Stylos;Ralf Ehret;Jan Karstens;Arkin Efeoglu;Daniela K. Busse

  • Affiliations:
  • School of Computer Science, Carnegie Mellon University, Pittsburgh, USA 15213;School of Computer Science, Carnegie Mellon University, Pittsburgh, USA 15213;School of Computer Science, Carnegie Mellon University, Pittsburgh, USA 15213;School of Computer Science, Carnegie Mellon University, Pittsburgh, USA 15213;School of Computer Science, Carnegie Mellon University, Pittsburgh, USA 15213;SAP, AG, Walldorf, Germany;SAP, AG, Walldorf, Germany;SAP, AG, Walldorf, Germany;SAP Labs, LLC Palo Alto CA 94304

  • Venue:
  • IS-EUD '09 Proceedings of the 2nd International Symposium on End-User Development
  • Year:
  • 2009

Quantified Score

Hi-index 0.00

Visualization

Abstract

All software today is written using libraries, toolkits, frameworks and other application programming interfaces (APIs). We performed a user study of the online documentation 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 user groups range from high-level business experts who do not have significant programming expertise (and thus are end-participant developers), to professional programmers. Our study showed that the participants' background influenced how they navigated the documentation. Lack of familiarity with business terminology was a barrier we observed for developers without business application experience. Participants with business software experience had difficulty differentiating similarly named services. Both groups avoided areas of the documentation that had an inconsistent visual design. A new design for the documentation that supports flexible navigation strategies seem to be required to support the wide range of users for eSOA. This paper summarizes our study and provides recommendations for future documentation for developers.