skip to main content
10.1145/3641822.3641881acmconferencesArticle/Chapter ViewAbstractPublication PagesicseConference Proceedingsconference-collections
short-paper

Why People Contribute Software Documentation

Published: 12 June 2024 Publication History

Abstract

Software technologies are used by a large population of programmers with diverse backgrounds. To fulfill their need for information, enthusiasts contribute numerous learning resources that vary in style and content, and act as documentation for the corresponding technology. We interviewed 26 volunteer contributors to understand why they create such documentation. We surface five motivations our informants had for contributing documentation, including to overcome issues they had faced with documentation and to capture their own learning. Among other findings, our observations suggest that the unique experience and background of documentation contributors provides the opportunity to create documentation that caters to users who have information needs and preferences similar to that of the contributor.

References

[1]
Emad Aghajani, Csaba Nagy, Mario Linares-Vásquez, Laura Moreno, Gabriele Bavota, Michele Lanza, and David C. Shepherd. 2020. Software Documentation: The Practitioners' Perspective. In Proceedings of the International Conference on Software Engineering.
[2]
Emad Aghajani, Csaba Nagy, Olga Lucero Vega-Márquez, Mario Linares-Vásquez, Laura Moreno, Gabriele Bavota, and Michele Lanza. 2019. Software Documentation Issues Unveiled. In Proceedings of International Conference on Software Engineering.
[3]
George Ajam, Babylon Hilla, Carlos Rodrıguez, and Boualem Benatallah. 2021. Scout-bot: Leveraging API Community Knowledge for Exploration and Discovery of API Learning Resources. CLEI electronic journal (2021).
[4]
Deeksha M. Arya, Jin L. C. Guo, and Martin P. Robillard. 2022. How programmers find online learning resources. Empirical Software Engineering (2022).
[5]
Deeksha M. Arya, Mathieu Nassif, and Martin P. Robillard. 2021. A Data-centric study of software tutorial design. IEEE Software (2021).
[6]
Suzanne Briet. 1951. Qu'est-ce que la documentation? Éditions documentaires, industrielles et techniques.
[7]
Souti Chattopadhyay, Thomas Zimmermann, and Denae Ford. 2021. Reel life vs. real life: How software developers share their daily life through vlogs. In Proceedings of the Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Software Engineering.
[8]
Steve Delanghe. 2000. Using learning styles in software documentation. Transactions on Professional Communication (2000).
[9]
Ralph H. Earle, Mark A. Rosso, and Kathryn E. Alexander. 2015. User preferences of software documentation genres. In Proceedings of the Annual International Conference on the Design of Communication.
[10]
Javier Escobar-Avila, Deborah Venuti, Massimiliano Di Penta, and Sonia Haiduc. 2019. A survey on online learning preferences for computer science and programming. In Proceedings of the International Conference on Software Engineering: Software Engineering Education and Training.
[11]
Alastair Gill, Scott Nowson, and Jon Oberlander. 2009. What are they blogging about? Personality, topic and motivation in blogs. In Proceedings of the International AAAI Conference on Web and Social Media.
[12]
Greg Guest, Arwen Bunce, and Laura Johnson. 2006. How many interviews are enough?: An experiment with data saturation and variability. Field Methods (2006).
[13]
Andrew Head, Jason Jiang, James Smith, Marti A. Hearst, and Björn Hartmann. 2020. Composing flexibly-organized step-by-step tutorials from linked source code, snippets, and outputs. In Proceedings of the Conference on Human Factors in Computing Systems.
[14]
Andre Hora. 2021. Googling for software development: What developers search for and what they find. In Proceedings of the International Conference on Mining Software Repositories.
[15]
Amber Horvath, Michael Xieyang Liu, River Hendriksen, Connor Shannon, Emma Paterson, Kazi Jawad, Andrew Macvean, and Brad A Myers. 2022. Understanding How Programmers Can Use Annotations on Documentation. In Proceedings of the Conference on Human Factors in Computing Systems.
[16]
Amber Horvath, Mariann Nagy, Finn Voichick, Mary Beth Kery, and Brad A. Myers. 2019. Methods for investigating mental models for learners of APIs. In Extended Abstracts of the Conference on Human Factors in Computing Systems.
[17]
Sheng-Bo Huang, Yu-Lin Jeng, and Chin-Feng Lai. 2021. Note-taking learning system: The use of the learning style theory and the peer learning method on computer programming course. Journal of Educational Computing Research (2021).
[18]
William Hudson. 2013. Chapter 22 - Card sorting. In The Encyclopedia of Human-Computer Interaction. Interaction Design Foundation.
[19]
He Jiang, Jingxuan Zhang, Zhilei Ren, and Tao Zhang. 2017. An unsupervised approach for discovering relevant tutorial fragments for APIs. In Proceedings of the International Conference on Software Engineering.
[20]
Robert Law. 2011. Using student blogs for documentation in software development projects. In Proceedings of the 16th Annual Joint Conference on Innovation and Technology in Computer Science Education.
[21]
Jonathan Lazar, Jinjuan Heidi Feng, and Harry Hochheiser. 2017. Chapter 8 - Interviews and focus groups. Research Methods in Human Computer Interaction (Second Edition) (2017).
[22]
Dan Li. 2005. Why do you blog: A uses-and-gratifications inquiry into bloggers' motivations. Master's thesis.
[23]
Niels Windfled Lund. 2007. What is Documentation? English translation of the classic French text. Journal of Documentation (2007).
[24]
Laura MacLeod, Margaret-Anne Storey, and Andreas Bergen. 2015. Code, camera, action: How software developers document and share program knowledge using YouTube. In Proceedings of the IEEE International Conference on Program Comprehension.
[25]
Gregory R McArthur. 1986. If writers can't program and programmers can't write, who's writing user documentation?. In Proceedings of the International Conference on Systems Documentation.
[26]
Brad Mehlenbacher. 2002. Documentation: Not yet Implemented, but Coming Soon! The Human-Computer Interaction Handbook: Fundamentals, Evolving Technologies and Emerging Applications (2002).
[27]
Dennis Pagano and Walid Maalej. 2013. How do open source communities blog? Empirical Software Engineering (2013).
[28]
Chris Parnin, Christoph Treude, and Margaret-Anne Storey. 2013. Blogging developer knowledge: Motivations, challenges, and future directions. In Proceedings of the International Conference on Program Comprehension.
[29]
David Piorkowski, Scott D. Fleming, Christopher Scaffidi, Margaret Burnett, Irwin Kwan, Austin Z. Henley, Jamie Macbeth, Charles Hill, and Amber Horvath. 2015. To fix or to learn? How production bias affects developers' information foraging during debugging. In Proceedings of the IEEE International Conference on Software Maintenance and Evolution.
[30]
Peter Pirolli and Stuart Card. 1999. Information foraging. Psychological Review (1999).
[31]
Peter Pirolli and Wai-tat Fu. 2003. SNIF-ACT: A model of information foraging on the World Wide Web. In Proceedings of the International Conference on User Modeling.
[32]
Marc Rettig. 1991. Nobody Reads Documentation. Commun. ACM (1991).
[33]
Carol Sansone and Jessi L. Smith. 2000. The "How" of Goal Pursuit: Interest and Self-Regulation. Psychological Inquiry (2000).
[34]
Yulia Shmerlin, Irit Hadar, Doron Kliger, and Hayim Makabee. 2015. To document or not to document? An exploratory study on developers' motivation to document code. In Advanced Information Systems Engineering Workshops.
[35]
Beth Simon, Krista Davis, William G. Griswold, Michael Kelly, and Roshni Malani. 2008. Noteblogging: Taking note taking public. In Proceedings of the SIGCSE Technical Symposium on Computer Science Education.
[36]
Jeffrey Stylos, Brad A. Myers, and Zizhuang Yang. 2009. Jadeite: Improving API Documentation Using Usage Information. In Extended Abstracts on Human Factors in Computing Systems.
[37]
Christoph Treude and Maurício Aniche. 2018. Where does Google find API documentation?. In Proceedings of the International Workshop on API Usage and Evolution. Association for Computing Machinery.
[38]
Gias Uddin and Martin P Robillard. 2015. How API documentation fails. IEEE Software (2015).
[39]
Emmanuelle Vaast and Elizabeth J. Davidson. 2008. New actors and new media in technology discourse: An investigation of tech blogging. In Proceedings of the International Conference on Interaction Sciences.
[40]
Hans van der Meij and Jan van der Meij. 2014. A comparison of paper-based and video tutorials for software learning. Computers and Education (2014).
[41]
David Wong-Aitken, Diana Cukierman, and Parmit K. Chilana. 2022. "It depends on whether or not I'm lucky" How students in an introductory programming course discover, select, and assess the utility of web-based resources. In Proceedings of the ACM Conference on Innovation and Technology in Computer Science Education.
[42]
Wenjing Xie. 2016. "I am blogging...": A qualitative study of bloggers' motivations of writing blogs. Encyclopedia of E-Commerce Development, Implementation, and Management: (2016).

Cited By

View all
  • (2024)Do LLMs Meet the Needs of Software Tutorial Writers? Opportunities and Design ImplicationsProceedings of the 2024 ACM Designing Interactive Systems Conference10.1145/3643834.3660692(1760-1773)Online publication date: 1-Jul-2024

Recommendations

Comments

Information & Contributors

Information

Published In

cover image ACM Conferences
CHASE '24: Proceedings of the 2024 IEEE/ACM 17th International Conference on Cooperative and Human Aspects of Software Engineering
April 2024
210 pages
ISBN:9798400705335
DOI:10.1145/3641822
Permission to make digital or hard copies of all or part of this work for personal or classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full citation on the first page. Copyrights for components of this work owned by others than the author(s) must be honored. Abstracting with credit is permitted. To copy otherwise, or republish, to post on servers or to redistribute to lists, requires prior specific permission and/or a fee. Request permissions from [email protected].

Sponsors

In-Cooperation

  • Faculty of Engineering of University of Porto

Publisher

Association for Computing Machinery

New York, NY, United States

Publication History

Published: 12 June 2024

Check for updates

Author Tags

  1. software documentation
  2. documentation creation
  3. human factors

Qualifiers

  • Short-paper

Funding Sources

  • NSERC

Conference

CHASE '24
Sponsor:

Acceptance Rates

Overall Acceptance Rate 47 of 70 submissions, 67%

Upcoming Conference

ICSE 2025

Contributors

Other Metrics

Bibliometrics & Citations

Bibliometrics

Article Metrics

  • Downloads (Last 12 months)73
  • Downloads (Last 6 weeks)8
Reflects downloads up to 20 Feb 2025

Other Metrics

Citations

Cited By

View all
  • (2024)Do LLMs Meet the Needs of Software Tutorial Writers? Opportunities and Design ImplicationsProceedings of the 2024 ACM Designing Interactive Systems Conference10.1145/3643834.3660692(1760-1773)Online publication date: 1-Jul-2024

View Options

Login options

View options

PDF

View or Download as a PDF file.

PDF

eReader

View online with eReader.

eReader

Figures

Tables

Media

Share

Share

Share this Publication link

Share on social media