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 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 user groups range from high-level business experts who do not have significant programming expertise (and thus are end-participant 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.
This is a preview of subscription content, log in via an institution to check access.
Access this chapter
Tax calculation will be finalised at checkout
Purchases are for personal use only
Preview
Unable to display preview. Download preview PDF.
References
Beaton, J., et al.: Usability Challenges for Enterprise Service-Oriented Architecture APIs. In: 2008 IEEE Symposium on Visual Languages and Human-Centric Computing, VL/HCC 2008, Herrsching am Ammersee, Germany, September 15-18, pp. 193–196 (2008)
Beaton, J., et al.: Usability Evaluation for Enterprise SOA APIs. In: 2nd International Workshop on Systems Development in SOA Environments, SDSOA 2008 (Co-located with ICSE 2008), May 12, pp. 29–34. Leipzig, Germany (2008)
Bloch, J.: Effective Java Programming Language Guide. Addison-Wesley, Boston (2001)
Clarke, S.: Measuring API Usability. Dr. Dobbs Journal, S6–S9 (May 2004)
Cwalina, K., Abrams, B.: Framework Design Guidelines. Addison-Wesley, Upper-Saddle River (2005)
Ellis, B., Stylos, J., Myers, B.: The Factory Pattern in API Design: A Usability Evaluation. In: International Conference on Software Engineering (ICSE 2007), May 20-26, Minneapolis, MN, pp. 302–312 (2007)
Forward, A., Lethbridge, T.C.: The relevance of software documentation, tools, and technology: a survey. In: DocEng, McLean. pp. 26–33 (2002)
Friendly, L.: The design of distributed hyperlinked programming documentation. In: International Workshop on Hypermedia Design, June 1-2, pp. 151–173. Springer, Montpellier (1995)
Jones, S.: SOA Anti-Patterns. Jun 19, C4Media Inc.: InfoQ.com (2006), http://www.infoq.com/articles/SOA-anti-patterns
Ko, A.J., Myers, B.A., Aung, H.H.: Six Learning Barriers in End-User Programming Systems. In: IEEE Symposium on Visual Languages and Human-Centric Computing, Rome, Italy, September 26-29, pp. 199–206 (2004)
Myers, B.: Creating More Natural Programming Languages. In: VL 2000: IEEE Symposium on Visual Languages, Seattle, Washington, September 10-14 (2000) (Invited Keynote Address), http://www.cs.orst.edu/~burnett/vl2000
Nielsen, J.: Usability Engineering. Academic Press, Boston (1993)
Purho, V.: Heuristic inspections for documentation-10 recommended documentation heuristics. STC Usability SIG Newsletter, 6(4) (April 2000), http://www.stcsig.org/usability/newsletter/0004-docsheuristics.html
Stylos, J., et al.: A Case Study of API Design for Improved Usability. In: 2008 IEEE Symposium on Visual Languages and Human-Centric Computing, VL/HCC 2008, Herrsching am Ammersee, Germany, September 15-18, pp. 189–192 (2008)
Stylos, J., Clarke, S.: Usability Implications of Requiring Parameters in Objects’ Constructors. In: International Conference on Software Engineering (ICSE 2007), Minneapolis, MN, May 20-26, pp. 529–539 (2007)
Stylos, J., Myers, B.A., Yang, Z.: Improving API Documentation Using API Usage Information (submitted, 2009)
Stylos, J., Myers., B.A.: The Implications of Method Placement on API Learnability. In: Sixteenth ACM SIGSOFT Symposium on Foundations of Software Engineering (FSE 2008), Atlanta, GA, November 9-14, pp. 105–112 (2008)
Author information
Authors and Affiliations
Editor information
Editors and Affiliations
Rights and permissions
Copyright information
© 2009 Springer-Verlag Berlin Heidelberg
About this paper
Cite this paper
Jeong, S.Y. et al. (2009). Improving Documentation for eSOA APIs through User Studies. In: Pipek, V., Rosson, M.B., de Ruyter, B., Wulf, V. (eds) End-User Development. IS-EUD 2009. Lecture Notes in Computer Science, vol 5435. Springer, Berlin, Heidelberg. https://doi.org/10.1007/978-3-642-00427-8_6
Download citation
DOI: https://doi.org/10.1007/978-3-642-00427-8_6
Publisher Name: Springer, Berlin, Heidelberg
Print ISBN: 978-3-642-00425-4
Online ISBN: 978-3-642-00427-8
eBook Packages: Computer ScienceComputer Science (R0)