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

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

Brad A. Myers (Carnegie Mellon University, USA), Sae Young Jeong (Carnegie Mellon University, USA), Yingyu Xie (Carnegie Mellon University, USA), Jack Beaton (Nokia, Inc., USA), Jeff Stylos (Carnegie Mellon University, USA), Ralf Ehret (SAP, AG, Germany), Jan Karstens (SAP, AG, Germany), Arkin Efeoglu (SAP, AG, Germany) and Daniela K. Busse (SAP Labs, LLC, USA)
DOI: 10.4018/978-1-4666-0140-6.ch004
OnDemand PDF Download:
No Current Special Offers


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.
Chapter Preview

1 Introduction

“Service-Oriented Architecture” (SOA) is a way to structure large and distributed software systems, where services communicate over a network with the client and with other services, and can be combined into composite applications. Increasingly, companies are providing their operations, which may previously have required installing a custom application, as services on the Web, so they can be accessed from a browser. Enterprise SOA (eSOA) is focused specifically on supporting business processes across an enterprise by reusing existing services. When an eSOA application is being planned and developed, many kinds of people are involved. For example, business process experts, who might be titled “Solution Architects,” are knowledgeable about the business context but may not necessarily be professional programmers, and are often responsible for identifying and selecting which services will be used. These users might therefore be classified as “end-user developers” (Wulf, Paterno, & Lieberman, 2006). Specifications they write might then be passed to professional programmers, who are responsible for writing code that uses the actual services. Therefore, the documentation and some of the tools must be accessible to both business process experts and professional programmers.

In a service-oriented architecture, code on the user’s machine communicates with a remote service using messages across the Internet. When using Web services, the communication is usually encoded in XML, and the format of the messages might be described using a WSDL (Web Services Description Language) file, which has been formalized by the World Wide Web Consortium (e.g.,

As part of the “Natural Programming Project” (Myers, Pane, & Ko, 2004), we are interested in a whole range of usability issues around programming. Recently, we have begun to focus on the usability of libraries, frameworks, toolkits, and other application programming interfaces (APIs) (Ellis, Stylos, & Myers, 2007; Stylos, Faulring, Yang, & Myers, 2008; Stylos & Myers, 2008). APIs are crucial since most of modern development of all kinds involves finding, understanding, and connecting pre-built items, from small library calls to large-scale components. Enterprise SOA APIs are particularly interesting to study, because they can be large and complex, and therefore expose interesting issues of scale, and because they often target a wide range of developers.

Our previous research has shown that programming using eSOA APIs is not simple when the APIs are providing access to powerful business functionality (Beaton, Jeong, Xie, Stylos, & Myers, 2008; Beaton, Myers, Stylos, Jeong, & Xie, 2008). Some barriers we identified included long names for services, different behaviors of services due to different business behavior, parameters of the services as hierarchies of objects with complex dependencies driven by internal, not exposed, business logic, and lack of example code (Beaton, Jeong, et al., 2008; Beaton, Myers, et al., 2008). The current paper presents the results of a user study of the usability of the online documentation provided by SAP for their enterprise SOA product.

In summary, our results are that when navigating eSOA API documentation, users with business backgrounds did better, and they experienced the most benefit from process component documentation. The process component documentation provides diagrams showing the architecture of an eSOA API in terms of service interfaces, the service operations they contain, and the business objects to which they are connected. All users avoided sites with visual designs that were inconsistent with their starting pages. Developers without business application experience were unfamiliar with business terminology and so they focused on searching and scanning for individual terms with limited success. Based on these results, we recommend that documentation provide flexible ways to navigate for different users with different backgrounds. This study also inspired new documentation tools, which we briefly summarize at the end of this paper.

Complete Chapter List

Search this Book: