Studying the Documentation of an API for Enterprise Service-Oriented Architecture

Authors:
Brad A. Myers;Sae Young Jeong;Yingyu Xie;Jack Beaton;Jeff Stylos;Ralf Ehret;Jan Karstens;Arkin Efeoglu;Daniela K. Busse
Affiliations:
Carnegie Mellon University, USA;Carnegie Mellon University, USA;Carnegie Mellon University, USA;Nokia, Inc., USA;Carnegie Mellon University, USA;SAP AG, Germany;SAP AG, Germany;SAP AG, Germany;SAP Labs LLC, USA
Venue:
Journal of Organizational and End User Computing
Year:
2010

Citing 12
Cited 0

Effective Java programming language guide

Effective Java programming language guide
The relevance of software documentation, tools and technologies: a survey

Proceedings of the 2002 ACM symposium on Document engineering
Natural programming languages and environments

Communications of the ACM - End-user development: tools that empower users to create their own software solutions
Six Learning Barriers in End-User Programming Systems

VLHCC '04 Proceedings of the 2004 IEEE Symposium on Visual Languages - Human Centric Computing
Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (Microsoft Net Development Series)

Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (Microsoft Net Development Series)
Usability Implications of Requiring Parameters in Objects' Constructors

ICSE '07 Proceedings of the 29th international conference on Software Engineering
The Factory Pattern in API Design: A Usability Evaluation

ICSE '07 Proceedings of the 29th international conference on Software Engineering
Usability evaluation for enterprise SOA APIs

Proceedings of the 2nd international workshop on Systems development in SOA environments
The implications of method placement on API learnability

Proceedings of the 16th ACM SIGSOFT International Symposium on Foundations of software engineering
A case study of API redesign for improved usability

VLHCC '08 Proceedings of the 2008 IEEE Symposium on Visual Languages and Human-Centric Computing
Usability challenges for enterprise service-oriented architecture APIs

VLHCC '08 Proceedings of the 2008 IEEE Symposium on Visual Languages and Human-Centric Computing
Improving API documentation using API usage information

VLHCC '09 Proceedings of the 2009 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC)

Quantified Score

Hi-index	0.00

Visualization

Abstract

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.