Article Preview
Top1 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., http://www.w3.org/TR/wsdl).
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.