API Documentation

A Conceptual Evaluation Model
  • Sergio Inzunza
  • Reyes Juárez-Ramírez
  • Samantha Jiménez
Conference paper
Part of the Advances in Intelligent Systems and Computing book series (AISC, volume 746)


Application Programming Interface (API) is packed functionality to solve specific tasks. In order for developers to learn to use its functionality, APIs include some kind of documentation. Documentation is an important part of the API itself, but, providing high-quality documentation is not a straightforward task. Nowadays, most of the documentation does not include the information expected by users. Another problem is the lack of comprehensive evaluation methods that can help creator to identify missing or incomplete elements in their documentation.

This papers presents a set of basic (minimum) elements that any API documentation should consider in order to provide target user the information they need to learn and make proper use of the provided functionality. Then through a survey, we collect the importance that software developers give to each basic element. Using the importance values collected, a conceptual API Documentation evaluation method is proposed that can be used by documentation creator to identify the weakness in their documentation. Finally, the model applicability is tested using it to evaluate some popular online API documentation for various domains.


  1. 1.
    Barth, M.: API Evaluation An overview of API evaluation techniques (2012)Google Scholar
  2. 2.
    Zaponni, C.: GitHunt (2017)Google Scholar
  3. 3.
    Uddin, G., Robillard, M.P.: How API documentation fails. IEEE Softw. 32(4), 68–75 (2015)CrossRefGoogle Scholar
  4. 4.
    Ellmann, M.: On the similarity of software development documentation. In: Proceedings of the 2017 11th Joint Meeting on Foundations of Software Engineering - ESEC/FSE 2017, pp. 1030–1033 (2017)Google Scholar
  5. 5.
    Zhou, Y., Gu, R., Chen, T., Huang, Z.: Analyzing APIs documentation and code to detect directive defects, May 2017Google Scholar
  6. 6.
    Robillard, M.P., Chhetri, Y.B.: Recommending reference API documentation. Empir. Softw. Eng. 20(6), 1558–1586 (2015)CrossRefGoogle Scholar
  7. 7.
    Watson, R., Mark Stamnes, M., Jeannot-Schroeder, J., Spyridakis, J.H.: API documentation and software community values. In: The 31st ACM International Conference, p. 165 (2013)Google Scholar
  8. 8.
    Treude, C., Robillard, M.P.: Augmenting API documentation with insights from stack overflow. In: Proceedings of the 38th International Conference on Software Engineering - ICSE 2016, pp. 392–403 (2016)Google Scholar
  9. 9.
    Sillito, J., Begel, A.: App-directed learning: an exploratory study. In: 2013 6th International Workshop on Cooperative and Human Aspects of Software Engineering, CHASE 2013 - Proceedings, pp. 81–84 (2013)Google Scholar
  10. 10.
    Gruenbaum, P.: “Hello World!” - A Coder’s Guide to Writing API Documentation (2014)Google Scholar
  11. 11.
    Robillard, M.P., Deline, R.: A field study of API learning obstacles. Empir. Softw. Eng. 16(6), 703–732 (2011)CrossRefGoogle Scholar
  12. 12.
    Bloch, J.: How to design a good API and why it matters. In: Companion to the 21st ACM SIGPLAN Conference on OOPSLA 2006, p. 506 (2006)Google Scholar
  13. 13.
    Nykaza, J., Messinger, R., Boehme, F., Norman, C.L., Mace, M., Gordon, M.: what programmers really want: results of a needs assessment for SDK documentation, pp. 133–141 (2002)Google Scholar
  14. 14.
    Watson, R., Stamnes, M., Jeannot-Schroeder, J., Spyridakis, J.H.: API documentation and software community values: a survey of open-source API documentation. In: Proceedings of the 31st ACM International Conference on Design of Communication, pp. 165–174. ACM (2013)Google Scholar
  15. 15.
    Brandt, J., Guo, P.J., Lewenstein, J., Dontcheva, M., Klemmer, S.R.: Two studies of opportunistic programming: interleaving web foraging, learning, and writing code. In: Proceedings of the SIGCHI Conference on Human Factors in Computing Systems, pp. 1589–1598. ACM (2009)Google Scholar
  16. 16.
    Ponzanelli, L., Bavota, G., Mocci, A., Di Penta, M., Oliveto, R., Hasan, M., Russo, B., Haiduc, S., Lanza, M.: CodeTube: extracting relevant fragments from software development video tutorials luca. In: Proceedings of the 38th International Conference on Software Engineering - ICSE 2016, pp. 261–272 (2016)Google Scholar
  17. 17.
    Robillard, M., Walker, R., Zimmermann, T.: Recommendation systems for software engineering. IEEE Softw. 27(4), 80–86 (2010)CrossRefGoogle Scholar
  18. 18.
    Rama, G.M., Kak, A.: Some structural measures of API usability. Softw. Pract. Exp. 45(1), 75–110 (2015)CrossRefGoogle Scholar
  19. 19.
    De, B.: API Management, pp. 59–80 (2017)CrossRefGoogle Scholar
  20. 20.
    Monperrus, M., Eichberg, M., Tekes, E., Mezini, M.: What should developers be aware of? an empirical study on the directives of API documentation. Empir. Softw. Eng. 17(6), 703–737 (2012)CrossRefGoogle Scholar
  21. 21.
    Zhong, H., Su, Z.: Detecting API documentation errors. In: ACM SIGPLAN Notices, vol. 48(10), pp. 803–816 (2013)CrossRefGoogle Scholar
  22. 22.
    Jääskeläinen, R.: Think-aloud protocol. In: Handbook of Translation Studies, vol. 1, pp. 371–373 (2010)CrossRefGoogle Scholar
  23. 23.
    Wharton, C., Rieman, J., Lewis, C., Polson, P.: The cognitive walkthrough method: a practitioner’s guide. In: Usability Inspection Methods, pp. 105–140. John Wiley & Sons, Inc. (1994)Google Scholar
  24. 24.
    Watson, R.B.: Development and application of a heuristic to assess trends in API documentation. In: Proceedings of the 30th ACM International Conference on Design of Communication - SIGDOC 2012, p. 295 (2012)Google Scholar
  25. 25.
    Jackson, M., Crouch, S., Baxter, R.: Software evaluation: criteria-based assessment, pp. 1–13 (2011)Google Scholar

Copyright information

© Springer International Publishing AG, part of Springer Nature 2018

Authors and Affiliations

  • Sergio Inzunza
    • 1
  • Reyes Juárez-Ramírez
    • 1
  • Samantha Jiménez
    • 1
  1. 1.Universidad Autónoma de Baja CaliforniaTijuanaMexico

Personalised recommendations