Improving Documentation for eSOA APIs through User Studies

  • Sae Young Jeong
  • Yingyu Xie
  • Jack Beaton
  • Brad A. Myers
  • Jeff Stylos
  • Ralf Ehret
  • Jan Karstens
  • Arkin Efeoglu
  • Daniela K. Busse
Part of the Lecture Notes in Computer Science book series (LNCS, volume 5435)

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.

Keywords

Usability API Design Service-Oriented Architecture Web Services Documentation Business Solution Architects 

Preview

Unable to display preview. Download preview PDF.

Unable to display preview. Download preview PDF.

References

  1. 1.
    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)Google Scholar
  2. 2.
    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)Google Scholar
  3. 3.
    Bloch, J.: Effective Java Programming Language Guide. Addison-Wesley, Boston (2001)Google Scholar
  4. 4.
    Clarke, S.: Measuring API Usability. Dr. Dobbs Journal, S6–S9 (May 2004)Google Scholar
  5. 5.
    Cwalina, K., Abrams, B.: Framework Design Guidelines. Addison-Wesley, Upper-Saddle River (2005)Google Scholar
  6. 6.
    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)Google Scholar
  7. 7.
    Forward, A., Lethbridge, T.C.: The relevance of software documentation, tools, and technology: a survey. In: DocEng, McLean. pp. 26–33 (2002)Google Scholar
  8. 8.
    Friendly, L.: The design of distributed hyperlinked programming documentation. In: International Workshop on Hypermedia Design, June 1-2, pp. 151–173. Springer, Montpellier (1995)Google Scholar
  9. 9.
    Jones, S.: SOA Anti-Patterns. Jun 19, C4Media Inc.: InfoQ.com (2006), http://www.infoq.com/articles/SOA-anti-patterns
  10. 10.
    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)Google Scholar
  11. 11.
    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
  12. 12.
    Nielsen, J.: Usability Engineering. Academic Press, Boston (1993)MATHGoogle Scholar
  13. 13.
    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
  14. 14.
    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)Google Scholar
  15. 15.
    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)Google Scholar
  16. 16.
    Stylos, J., Myers, B.A., Yang, Z.: Improving API Documentation Using API Usage Information (submitted, 2009)Google Scholar
  17. 17.
    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)Google Scholar

Copyright information

© Springer-Verlag Berlin Heidelberg 2009

Authors and Affiliations

  • Sae Young Jeong
    • 1
  • Yingyu Xie
    • 1
  • Jack Beaton
    • 1
  • Brad A. Myers
    • 1
  • Jeff Stylos
    • 1
  • Ralf Ehret
    • 2
  • Jan Karstens
    • 2
  • Arkin Efeoglu
    • 2
  • Daniela K. Busse
    • 3
  1. 1.School of Computer ScienceCarnegie Mellon UniversityPittsburghUSA
  2. 2.SAP, AGWalldorfGermany
  3. 3.SAP LabsLLC Palo AltoUSA

Personalised recommendations