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 ServiceOriented 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 endparticipant 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.
SAP recently began offering access to web services through its Enterprise Service-Oriented Architecture (E-SOA) platform. It is in the best interest of SAP that its E-SOA service operations are easier for developers to use and understand, which will contribute to higher E-SOA adoption, and a more effective means of innovation on the part of business customers. To facilitate such a change, Carnegie Mellon University's Human-Computer Interaction Institute is working with SAP's E-SOA and Business Process Renovation Teams to analyze the E-SOA interfaces using HCI techniques and determine means by which developers assigned to create SOA APIs in general, and Enterprise SOA APIs in particular, can design superior interfaces. The identification of usable design patterns, and methodologies to determine these patterns, can streamline SOA projects for API developers and programmers who use SOA APIs.
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.
scite is a Brooklyn-based organization that helps researchers better discover and understand research articles through Smart Citations–citations that display the context of the citation and describe whether the article provides supporting or contrasting evidence. scite is used by students and researchers from around the world and is funded in part by the National Science Foundation and the National Institute on Drug Abuse of the National Institutes of Health.