Academic paper references

One of the challenges I had in graduate school was finding academic references that had to do with API documentation specifically and programmer-writing in general. In 2008, when I started researching the topic academically, you could count the references on one hand. Since then, the topic has gained some more popularity, but academic work on the subject still remains scarce. To help you in your search, help yourself to my bibliography here. My favorite references are highlighted.

If you have a favorite, please send it to me and I’ll add it to the list.

API documentation: What it is

  • Mihaly, F. (2011, November 1). Writing helpful API documentation. Retrieved from http://theamiableapi.com/2011/11/01/api-design-best-practice-write-helpful-documentation/
  • Nykaza, J., Messinger, R., Boehme, F., Norman, C. L., Mace, M., & Gordon, M. (2002). What programmers really want: results of a needs assessment for sdk documentation. In Proceedings of the 20th annual international conference on Computer documentation (pp. 133–141). ACM.
  • Watson, R. B. (2012). Development and application of a heuristic to assess trends in API documentation. In Proceedings of the 30th ACM international conference on Design of communication (pp. 295–302). Seattle, WA: ACM.
  • Watson, R., Stamnes, M., Jeannot-Schroeder, J., & Spyridakis, J. H. (2013). 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). New York, NY, USA: ACM. doi:10.1145/2507065.2507076

API documentation: Why it sucks

  • Maalej, W., & Robillard, M. P. (2013). Patterns of Knowledge in API Reference Documentation. IEEE Transactions on Software Engineering, 39(9), 1264–1282. doi:10.1109/TSE.2013.12
  • Parnin, C. (2013, March 4). API Documentation – Why it sucks [blog]. Retrieved November 2, 2014, from http://blog.ninlabs.com/2013/03/api-documentation/
  • Parnin, C., & Treude, C. (2011). Measuring api documentation on the web. In Measuring API Documentation on the Web (pp. 25–30). Waikiki, Honolulu, HI, USA: ACM.
  • Robillard, M. P. (2009). What makes apis hard to learn? answers from developers. Software, IEEE, 26(6), 27–34.
  • Robillard, M. P., & DeLine, R. (2011). A field study of API learning obstacles. Empirical Software Engineering, 16(6), 703–732.
  • Treude, C., & Aniche, M. (2018). Where does Google find API documentation?  WAPI’18: WAPI’18: IEEE/ACM 2nd International Workshop on API Usage and Evolution, June 2–4, 2018, Gothenburg, Sweden. ACM, New York, NY, USA
  • Uddin, G., & Robillard, M. P. (2015). How API Documentation Fails. IEEE Software, 32(4), 68–75. https://doi.org/10.1109/MS.2014.80
  • Yang, J., Wittern, E., Ying, A. T., Dolby, J., & Tan, L. (2018). Towards Extracting Web API Specifications from Documentation. In MSR ’18: 15th International Conference on Mining Software Repositories , May 28–29, 2018, Gothenburg, Sweden. ACM, New York, NY, USA.

API documentation: Writing it

  • Chen, C., & Zhang, K. (2014). Who Asked What: Integrating Crowdsourced FAQs into API Documentation. In Companion Proceedings of the 36th International Conference on Software Engineering (pp. 456–459). New York, NY, USA: ACM. https://doi.org/10.1145/2591062.2591128
  • Phan, H., Nguyen, H. A., Nguyen, T. N., & Rajan, H. (2017). Statistical Learning for Inference Between Implementations and Documentation. In Proceedings of the 39th International Conference on Software Engineering: New Ideas and Emerging Results Track (pp. 27–30). Piscataway, NJ, USA: IEEE Press. https://doi.org/10.1109/ICSE-NIER.2017.9
  • Rocha, A. M., & Maia, M. A. (2016). Automated API Documentation with Tutorials Generated From Stack Overflow. In Proceedings of the 30th Brazilian Symposium on Software Engineering (pp. 33–42). New York, NY, USA: ACM. https://doi.org/10.1145/2973839.2973847
  • Treude, C., & Robillard, M. P. (2016). Augmenting API Documentation with Insights from Stack Overflow. In Proceedings of the 38th International Conference on Software Engineering (pp. 392–403). New York, NY, USA: ACM. https://doi.org/10.1145/2884781.2884800

API usability and design

  • Clarke, S. (2005). Describing and measuring API usability with the cognitive dimensions. Presented at the Cognitive Dimensions of Notations 10th Anniversary Workshop, Citeseer.
  • Cwalina, K., & Abrams, B. (2008). Framework design guidelines: conventions, idioms, and patterns for reusable. net libraries. Addison-Wesley Professional.
  • Henning, M. (2007). API design matters. Queue, 5(4), 24–36.
  • Myers, B. A., & Stylos, J. (2016). Improving API Usability. Commun. ACM, 59(6), 62–69. https://doi.org/10.1145/2896587

Content analysis

  • Krippendorff, K. H. (2012). Content Analysis: An Introduction to Its Methodology (Third Edition edition.). Los Angeles ; London: SAGE Publications, Inc.

Education and learning

  • DeStefano, D., & LeFevre, J.-A. (2007). Cognitive load in hypertext reading: A review. Computers in Human Behavior, 23(3), 1616–1641.
  • Knowles, M. S., Swanson, R. A., & Holton, E. F. I. (2011). The Adult Learner, Seventh Edition: The definitive classic in adult education and human resource development (7th ed.). Taylor & Francis.
  • Piaget, J. (1970). Science of education and the psychology of the child (First printing.). New York: Orion Press.
  • Pollock, E., Chandler, P., & Sweller, J. (2002). Assimilating complex information. Learning and Instruction, 12(1), 61–86.
  • Rouet, J.-F. (2006). The Skills of Document Use: From Text Comprehension to Web-Based Learning (First Edition.). Lawrence Erlbaum Associates.
  • Skinner, B. (1954). The science of learning and the art of teaching. Harvard Educational Review.
  • Sweller, J. (1988). Cognitive load during problem solving: Effects on learning. Cognitive Science, 12(2), 257–285.
  • Valcke, M. (2002). Cognitive load: updating the theory? Learning and Instruction, 12(1), 147–154.

General design principles

  • Lidwell, W., Holden, K., & Butler, J. (2010). Universal Principles of Design, Revised and Updated: 125 Ways to Enhance Usability, Influence Perception, Increase Appeal, Make Better Design Decisions, and Teach through Design (Second Edition, Revised and Updated edition.). Rockport Publishers.

Software developers using documentation

  • Aggarwal, K., Hindle, A., & Stroulia, E. (2014). Co-evolution of Project Documentation and Popularity Within Github. In Proceedings of the 11th Working Conference on Mining Software Repositories (pp. 360–363). New York, NY, USA: ACM. https://doi.org/10.1145/2597073.2597120
  • Brandt, J., Dontcheva, M., Weskamp, M., & Klemmer, S. R. (2010). Example-centric programming: integrating web search into the development environment (pp. 513–522). Presented at the Proceedings of the SIGCHI Conference on Human Factors in Computing Systems, ACM.
  • Brandt, J., Guo, P. J., Lewenstein, J., Dontcheva, M., & Klemmer, S. R. (2009). Two studies of opportunistic programming: interleaving web foraging, learning, and writing code (pp. 1589–1598). Presented at the Proceedings of the SIGCHI
  • Brandt, J., Guo, P. J., Lewenstein, J., & Klemmer, S. R. (2008). Opportunistic programming: How rapid ideation and prototyping occur in practice (pp. 1–5). Presented at the Proceedings of the 4th international workshop on End-user
  • Clarke, S. (2007, February 7). What is an End User Software Engineer? [InProceedings]. Retrieved October 26, 2014, from http://drops.dagstuhl.de/opus/volltexte/2007/1080/
  • DeMarco, T., & Lister, T. (2013). Peopleware: Productive Projects and Teams (3rd Edition.). Upper Saddle River, NJ: Addison-Wesley Professional.
  • Head, A., Sadowski, C., Murphy-Hill, E., & Knight, A. (2018). When not to comment: questions and tradeoffs with API documentation for C++ projects (pp. 643–653). In Proceedings of ICSE ’18: 40th International Conference on Software Engineering , Gothenburg, Sweden, May 27-June 3, 2018 (ICSE ’18).
  • Ko, A. J., Myers, B. A., Coblenz, M. J., & Aung, H. H. (2006). An exploratory study of how developers seek, relate, and collect relevant information during software maintenance tasks. Software Engineering, IEEE Transactions on, 32(12), 971–987.
  • Saied, M. A., Sahraoui, H., & Dufour, B. (2015). An observational study on API usage constraints and their documentation. In 2015 IEEE 22nd International Conference on Software Analysis, Evolution, and Reengineering (SANER) (pp. 33–42). https://doi.org/10.1109/SANER.2015.7081813
  • Sadowski, C., Stolee, K. T., & Elbaum, S. (2015). How developers search for code: a case study (pp. 191–201). Presented at the Proceedings of the 2015 10th Joint Meeting on Foundations of Software Engineering, ACM.
  • Samuelson, P., & Scotchmer, S. (2002). The Law and Economics of Reverse Engineering. The Yale Law Journal, 111(7), 1575–1663. doi:10.2307/797533
  • Stylos, J., & Myers, B. A. (2005). How Programmers Use Internet Resources to Aid Programming. Submitted for Publication.
  • Stylos, J., & Myers, B. A. (2006). Mica: A web-search tool for finding API components and examples. In Proceedings of the Visual Languages and Human-Centric Computing, 2006. VL/HCC 2006. IEEE Symposium on (pp. 195–202). IEEE.

Web design

  • McGovern, G. (2006). Killer Web Content: Make the Sale, Deliver the Service, Build the Brand (1 edition.). London: A&C Black Trade.
  • Redish, J. (2012). Letting Go of the Words, Second Edition: Writing Web Content that Works (2 edition.). Amsterdam ; Boston: Morgan Kaufmann.
  • Reynolds, G. (2008). Presentation Zen: Simple Ideas on Presentation Design and Delivery (1 edition.). Berkeley, CA: New Riders.
  • Robins, D., & Holmes, J. (2008). Aesthetics and credibility in web site design. Information Processing & Management, 44(1), 386–399.
  • Tidwell, J. (2011). Designing Interfaces (Second Edition edition.). Sebastopol, CA: O’Reilly Media.
  • Tractinsky, N. (2004). A few notes on the study of beauty in HCI. Human–Computer Interaction, 19(4), 351–357.
  • Tractinsky, N., Cokhavi, A., Kirschenbaum, M., & Sharfi, T. (2006). Evaluating the consistency of immediate aesthetic perceptions of web pages. International Journal of Human-Computer Studies, 64(11), 1071–1083.
  • Tractinsky, N., Katz, A., & Ikar, D. (2000). What is beautiful is usable. Interacting with Computers, 13(2), 127–145.
  • Van Schaik, P., & Ling, J. (2008). Modelling user experience with web sites: Usability, hedonic value, beauty and goodness. Interacting with Computers, 20(3), 419–432.
  • Van Schaik, P., & Ling, J. (2009). The role of context in perceptions of the aesthetics of web pages over time. International Journal of Human-Computer Studies, 67(1), 79–89.

Leave a Reply