Studying the Documentation of an API for Enterprise Service-Oriented Architecture
Authors:
- 1 January 2010
- journal article
- research article
- Published by IGI Global Scientific Publishing in Journal of Organizational and End User Computing
- Vol. 22 (1) , 23-51
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.Keywords
This publication has 25 references indexed in Scilit:
- THE WAY I SEE ITWorkarounds and hacksInteractions, 2008
- Component-based tailorability: Enabling highly flexible software applicationsInternational Journal of Human-Computer Studies, 2008
- Combining Tailoring and Evolutionary Software Development for Rapidly Changing Business SystemsJournal of Organizational and End User Computing, 2007
- Natural programming languages and environmentsCommunications of the ACM, 2004
- Meta-designCommunications of the ACM, 2004
- Component-based technologies for end-user developmentCommunications of the ACM, 2004
- New forms of learning in co‐configuration workJournal of Workplace Learning, 2004
- Why promising technologies fail: the neglected role of user innovation during adoptionResearch Policy, 2001
- Direct activation: A concept to encourage tailoring activitiesBehaviour & Information Technology, 2001
- Institutional Ecology, `Translations' and Boundary Objects: Amateurs and Professionals in Berkeley's Museum of Vertebrate Zoology, 1907-39Social Studies of Science, 1989