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, Sae Young Jeong, Yingyu Xie, Jack Beaton, Jeff Stylos, Ralf Ehret, Jan Karstens, Arkin Efeoglu, Daniela K. Busse
Copyright: © 2010 |Pages: 29
DOI: 10.4018/joeuc.2010101903
(Individual Articles)
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.
Article Preview


The goal of the research reported here is to identify areas where end-user development (EUD) and professional software development meet and interact. We have observed and participated in development activities in a commercial software house (referred to as company) over a period of two years. We propose a model of the activities, which we refer to as mutual development. The model consists of the 5 sub-processes, which connects EUD and professional development.


There are two levels of software development: specific and general, represented by the activities of amateur (end-user) and professional developers, respectively. When they interact in a mutually beneficial way a new opportunity for innovation emerges that extends the boundaries of what can be accomplished with in-house driven innovation (Victor & Boynton, 1998). We call this model “inside-out” and the model advocated in this chapter “outside-in.” Inside-out innovation is initiated by professional developers and technology managers, that is, technological innovation, whereas outside-in is driven by external events, a type of innovation that originates outside professional communities by end users (Fischer, 2002) and customers (von Hippel, 2005). They are amateur (non professional) developers who act on behalf of specific needs and by creating ad hoc modifications to “finished” products. The mutual dependency between technological and user-driven innovation can be exemplified by the development of Levi’s blue jeans. In 1873 Jacob Davis and Levi Strauss invented to rivet (copper nail) the pocket corners on men’s working pants to make them stronger. The two men were granted a patent on this, which is widely recognized as the invention of the blue jean. It is an example of technological innovation. Later on, in 1937 the rivets (copper nails) were removed on the back pockets (first sewn so that they were hidden, and during the Second World War removed to save metal). The hiding and removal of the rivets were in response to consumers who complained that the rivets scratched furniture and saddles. This was a user-driven innovation triggered by various external events that modified a technological invention into a more useful design (Levi Strauss & Co., 2009). It serves as a motivating example for the topic of this article, which is about mutual development: the integration of end-user development and professional software development.

Mutual development is based on a technique for participatory design (PD) known as mutual learning (Bratteteig, 1997). Mutual learning is a technique for users to learn about software design from professional developers, and developers learning the professional (workplace) language of domain-expert users. Mutual development takes this a step further in that the shared knowledge established during mutual learning serves as platform for end-user development. The goal is not only to support collaboration between developers and users (as in PD), but also to empower them with new tools and new forms of organization. This is arguable easier when there are two distinct levels of development, one for software engineers and another for end-user developers. Rich communication channels to connect them can stimulate formalizing ad hoc modifications into software artifacts, and a good process of collaborative design can transform an end-user developed solution into a commercial product feature (Mørch, Nygård, & Ludvigsen, 2009). Users will be increasingly motivated to participate in end-user development when the activity has impact beyond a local solution.

Complete Article List

Search this Journal:
Volume 36: 1 Issue (2024)
Volume 35: 3 Issues (2023)
Volume 34: 10 Issues (2022)
Volume 33: 6 Issues (2021)
Volume 32: 4 Issues (2020)
Volume 31: 4 Issues (2019)
Volume 30: 4 Issues (2018)
Volume 29: 4 Issues (2017)
Volume 28: 4 Issues (2016)
Volume 27: 4 Issues (2015)
Volume 26: 4 Issues (2014)
Volume 25: 4 Issues (2013)
Volume 24: 4 Issues (2012)
Volume 23: 4 Issues (2011)
Volume 22: 4 Issues (2010)
Volume 21: 4 Issues (2009)
Volume 20: 4 Issues (2008)
Volume 19: 4 Issues (2007)
Volume 18: 4 Issues (2006)
Volume 17: 4 Issues (2005)
Volume 16: 4 Issues (2004)
Volume 15: 4 Issues (2003)
Volume 14: 4 Issues (2002)
Volume 13: 4 Issues (2001)
Volume 12: 4 Issues (2000)
Volume 11: 4 Issues (1999)
Volume 10: 4 Issues (1998)
Volume 9: 4 Issues (1997)
Volume 8: 4 Issues (1996)
Volume 7: 4 Issues (1995)
Volume 6: 4 Issues (1994)
Volume 5: 4 Issues (1993)
Volume 4: 4 Issues (1992)
Volume 3: 4 Issues (1991)
Volume 2: 4 Issues (1990)
Volume 1: 3 Issues (1989)
View Complete Journal Contents Listing