Document Open Access Logo

On the Rise of Modern Software Documentation (Pearl/Brave New Idea)

Authors Marco Raglianti , Csaba Nagy , Roberto Minelli , Bin Lin , Michele Lanza

PDF
Thumbnail PDF

File

LIPIcs.ECOOP.2023.43.pdf
  • Filesize: 2.94 MB
  • 24 pages

Document Identifiers

Author Details

Marco Raglianti
  • REVEAL @ Software Institute — USI, Lugano, Switzerland
Csaba Nagy
  • REVEAL @ Software Institute — USI, Lugano, Switzerland
Roberto Minelli
  • REVEAL @ Software Institute — USI, Lugano, Switzerland
Bin Lin
  • Radboud University, Nijmegen, The Netherlands
Michele Lanza
  • REVEAL @ Software Institute — USI, Lugano, Switzerland

Funding

This work is supported by the Swiss National Science Foundation (SNSF) through the project "INSTINCT" (SNF Project No. 190113).

Acknowledgements

Marco Raglianti would also like to thank the Swiss Group for Original and Outside-the-box Software Engineering (CHOOSE) for sponsoring the trip to the conference.

Cite AsGet BibTex

Marco Raglianti, Csaba Nagy, Roberto Minelli, Bin Lin, and Michele Lanza. On the Rise of Modern Software Documentation (Pearl/Brave New Idea). In 37th European Conference on Object-Oriented Programming (ECOOP 2023). Leibniz International Proceedings in Informatics (LIPIcs), Volume 263, pp. 43:1-43:24, Schloss Dagstuhl – Leibniz-Zentrum für Informatik (2023)
https://doi.org/10.4230/LIPIcs.ECOOP.2023.43

Abstract

Classical software documentation, as it was conceived and intended decades ago, is not the only reality anymore. Official documentation from authoritative and official sources is being replaced by real-time collaborative platforms and ecosystems that have seen a surge, influenced by changes in society, technology, and best practices. These modern tools influence the way developers document the conception, design, and implementation of software. As a by-product of these shifts, developers are changing their way of communicating about software. Where once official documentation stood as the only truth about a project, we now find a multitude of volatile and heterogeneous documentation sources, forming a complex and ever-changing documentation landscape. Software projects often include a top-level README file with important information, which we leverage to identify their documentation landscape. Starting from ∼12K GitHub repositories, we mine their README files to extract links to additional documentation sources. We present a qualitative analysis, revealing multiple dimensions of the documentation landscape (e.g., content type, source type), highlighting important insights. By analyzing instant messaging application links (e.g., Gitter, Slack, Discord) in the histories of README files, we show how this part of the landscape has grown and evolved in the last decade. Our findings show that modern documentation encompasses communication platforms, which are exploding in popularity. This is not a passing phenomenon: On the contrary, it entails a number of unknowns and socio-technical problems the research community is currently ill-prepared to tackle.

Subject Classification

ACM Subject Classification
  • Software and its engineering → Collaboration in software development
  • Human-centered computing → Collaborative and social computing
Keywords
  • software documentation landscape
  • GitHub README
  • instant messaging

Metrics

  • Access Statistics
  • Total Accesses (updated on a weekly basis)
    0
    PDF Downloads
    0
    Metadata Views

Supplementary Materials

References

  1. A Medium Corporation. Medium. URL: https://medium.com/.
  2. Tim Abbott. Why Slack’s free plan change is causing an exodus. URL: https://blog.zulip.com/2022/08/26/why-slacks-free-plan-change-is-causing-an-exodus/.
  3. Emad Aghajani, Csaba Nagy, Mario Linares-Vásquez, Laura Moreno, Gabriele Bavota, Michele Lanza, and David C. Shepherd. Software documentation: The practitioners' perspective. In Proceedings of ICSE 2020 (International Conference on Software Engineering), pages 590-601. ACM, 2020. Google Scholar
  4. Emad Aghajani, Csaba Nagy, Olga Lucero Vega-Márquez, Mario Linares-Vásquez, Laura Moreno, Gabriele Bavota, and Michele Lanza. Software documentation issues unveiled. In Proceedings of ICSE 2019 (International Conference on Software Engineering), pages 1199-1210. IEEE/ACM, 2019. Google Scholar
  5. Rana Alkadhi, Teodora Lata, Emitza Guzmany, and Bernd Bruegge. Rationale in development chat messages: An exploratory study. In Proceedings of MSR 2017 (International Conference on Mining Software Repositories), pages 436-446. IEEE/ACM, 2017. Google Scholar
  6. Maurício Aniche, Christoph Treude, Igor Steinmacher, Igor Wiese, Gustavo Pinto, Margaret-Anne Storey, and Marco Aurélio Gerosa. How modern news aggregators help development communities shape and share knowledge. In Proceedings of ICSE 2018 (International Conference on Software Engineering), pages 499-510. ACM, 2018. Google Scholar
  7. Alberto Bacchelli and Christian Bird. Expectations, outcomes, and challenges of modern code review. In Proceedings of ICSE 2013 (International Conference on Software Engineering), pages 712-721. IEEE, 2013. Google Scholar
  8. Hudson Borges and Marco Tulio Valente. What’s in a GitHub star? Understanding repository starring practices in a social coding platform. Journal of Systems and Software, 146:112-129, 2018. Google Scholar
  9. Preetha Chatterjee, Kostadin Damevski, Lori Pollock, Vinay Augustine, and Nicholas A Kraft. Exploratory study of Slack Q&A chats as a mining source for software engineering tools. In Proceedings of MSR 2019 (International Conference on Mining Software Repositories), pages 490-501. IEEE/ACM, 2019. Google Scholar
  10. Jie-Cherng Chen and Sun-Jen Huang. An empirical analysis of the impact of software development problem factors on software maintainability. Journal of Systems and Software, 82(6):981-992, 2009. Google Scholar
  11. Codecov. Codecov. URL: https://about.codecov.io/.
  12. David Curry. Slack revenue and usage statistics (2022). URL: https://www.businessofapps.com/data/slack-statistics/.
  13. Ozren Dabic, Emad Aghajani, and Gabriele Bavota. Sampling projects in GitHub for MSR studies. In Proceedings of MSR 2021 (International Conference on Mining Software Repositories), pages 560-564. IEEE/ACM, 2021. Google Scholar
  14. Barthélémy Dagenais and Martin P Robillard. Creating and evolving developer documentation: Understanding the decisions of open source contributors. In Proceedings of FSE 2010 (International Symposium on Foundations of Software Engineering), pages 127-136. ACM, 2010. Google Scholar
  15. Discord. Invites 101. URL: https://support.discord.com/hc/en-us/articles/208866998-Invites-101.
  16. Discord, Inc. Discord. URL: https://discord.com/.
  17. Verena Ebert, Daniel Graziotin, and Stefan Wagner. How are communication channels on GitHub presented to their intended audience? - A thematic analysis. In Proceedings of EASE 2022 (International Conference on Evaluation and Assessment in Software Engineering), pages 40-49. ACM, 2022. Google Scholar
  18. Osama Ehsan, Safwat Hassan, Mariam El Mezouar, and Ying Zou. An empirical study of developer discussions in the Gitter platform. Transactions on Software Engineering and Methodology, 30(1):1-39, 2020. Google Scholar
  19. Andrew Forward and Timothy C Lethbridge. The relevance of software documentation, tools and technologies: A survey. In Proceedings of DocEng 2002 (Symposium on Document Engineering), pages 26-33. ACM, 2002. Google Scholar
  20. freeCodeCamp. Our experience with Slack. URL: https://www.freecodecamp.org/news/so-yeah-we-tried-slack-and-we-deeply-regretted-it-391bcc714c81.
  21. Golara Garousi, Vahid Garousi-Yusifoğlu, Guenther Ruhe, Junji Zhi, Mahmoud Moussavi, and Brian Smith. Usage and usefulness of technical software documentation: An industrial case study. Information and Software Technology, 57:664-682, 2015. Google Scholar
  22. GitHub. Fork a repo. URL: https://docs.github.com/en/get-started/quickstart/fork-a-repo.
  23. GitHub. PyGithub. URL: https://github.com/PyGithub/PyGithub.
  24. GitHub, Inc. GitHub. URL: https://github.com/.
  25. Google, LLC. YouTube. URL: https://www.youtube.com/.
  26. Emitza Guzman, Rana Alkadhi, and Norbert Seyff. A needle in a haystack: What do Twitter users say about software? In Proceedings of RE 2016 (International Requirements Engineering Conference), pages 96-105. IEEE, 2016. Google Scholar
  27. Hideaki Hata, Nicole Novielli, Sebastian Baltes, Raula Gaikovina Kula, and Christoph Treude. GitHub Discussions: An exploratory study of early adoption. Empirical Software Engineering, 27(1):1-32, 2022. Google Scholar
  28. Hideaki Hata, Christoph Treude, Raula Gaikovina Kula, and Takashi Ishio. 9.6 million links in source code comments: Purpose, evolution, and decay. In Proceedings of ICSE 2019 (International Conference on Software Engineering), pages 1211-1221. IEEE, 2019. Google Scholar
  29. Martin Hoegl and Hans Gemuenden. Teamwork quality and the success of innovative projects: A theoretical concept and empirical evidence. Organization Science, 12(4):435-449, 2001. Google Scholar
  30. Jialun Aaron Jiang, Charles Kiene, Skyler Middler, Jed R. Brubaker, and Casey Fiesler. Moderation challenges in voice-based online communities on Discord. Proceedings of HCI 2019 (Human-Computer Interaction), 3(CSCW):1-23, 2019. Google Scholar
  31. Verena Käfer, Daniel Graziotin, Ivan Bogicevic, Stefan Wagner, and Jasmin Ramadani. Communication in Open-Source projects - End of the e-mail era? In Proceedings of ICSE 2018 (International Conference on Software Engineering), pages 242-243. ACM, 2018. Google Scholar
  32. Marcia Lima, Igor Steinmacher, Denae Ford, Evangeline Liu, Grace Vorreuter, Tayana Conte, and Bruno Gadelha. Looking for related discussions on GitHub Discussions. In arXiv, 2022. Google Scholar
  33. Bin Lin, Alexey Zagalsky, Margaret-Anne Storey, and Alexander Serebrenik. Why developers are slacking off: Understanding how software teams use Slack. In Proceedings of CSCW/SCC 2016, pages 333-336. ACM, 2016. Google Scholar
  34. Yngve Lindsjørn, Dag I.K. Sjøberg, Torgeir Dingsøyr, Gunnar R. Bergersen, and Tore Dybå. Teamwork quality and project success in software development: A survey of agile development teams. Journal of Systems and Software, 122:274-286, 2016. Google Scholar
  35. LinkedIn Corporation. LinkedIn. URL: https://www.linkedin.com.
  36. Brian Lovin. Join us on our new journey. URL: https://web.archive.org/web/20220927203327/https://spectrum.chat/spectrum/general/join-us-on-our-new-journey~e4ca0386-f15c-4ba8-8184-21cf5fa39cf5.
  37. Meta. Facebook. URL: https://www.facebook.com/.
  38. Mariam El Mezouar, Feng Zhang, and Ying Zou. Are tweets useful in the bug fixing process? An empirical study on Firefox and Chrome. Empirical Software Engineering, 23(3):1704-1742, 2018. Google Scholar
  39. New Vector, Ltd. Gitter. URL: https://gitter.im/.
  40. Yusuf Sulistyo Nugroho, Syful Islam, Keitaro Nakasai, Ifraz Rehman, Hideaki Hata, Raula Gaikovina Kula, Meiyappan Nagappan, and Kenichi Matsumoto. How are project-specific forums utilized? A study of participation, content, and sentiment in the Eclipse ecosystem. Empirical Software Engineering, 26(6):132, 2021. Google Scholar
  41. N. Nurmuliani, D. Zowghi, and S. P. Williams. Using card sorting technique to classify requirements change. In Proceedings of IREC 2004 (International Requirements Engineering Conference), pages 240-248. IEEE, 2004. Google Scholar
  42. OpenAPI Tools. OpenAPI Generator. URL: https://github.com/OpenAPITools/openapi-generator.
  43. Dennis Pagano and Walid Maalej. How do developers blog? An exploratory study. In Proceedings of MSR 2011 (Working Conference on Mining Software Repositories), pages 123-132. ACM, 2011. Google Scholar
  44. Papyrs. Easy company intranet & internal team wiki for Slack. URL: https://papyrs.com/slack-wiki-intranet/.
  45. Esteban Parra, Mohammad Alahmadi, Ashley Ellis, and Sonia Haiduc. A comparative study and analysis of developer communications on Slack and Gitter. Empirical Software Engineering, 27(2):1-33, 2022. Google Scholar
  46. Esteban Parra, Ashley Ellis, and Sonia Haiduc. GitterCom: A dataset of Open Source developer communications in Gitter. In Proceedings of MSR 2020 (International Conference on Mining Software Repositories), pages 563-567. ACM, 2020. Google Scholar
  47. Luca Ponzanelli, Gabriele Bavota, Massimiliano Di Penta, Rocco Oliveto, and Michele Lanza. Mining StackOverflow to turn the IDE into a self-confident programming prompter. In Proceedings of MSR 2014 (Working Conference on Mining Software Repositories), pages 102-111. IEEE/ACM, 2014. Google Scholar
  48. Python Software Foundation. Python Package Index. URL: https://pypi.org/.
  49. Marco Raglianti, Roberto Minelli, Csaba Nagy, and Michele Lanza. Visualizing Discord servers. In Proceedings of VISSOFT 2021 (Working Conference on Software Visualization), pages 150-154. IEEE, 2021. Google Scholar
  50. Marco Raglianti, Csaba Nagy, Roberto Minelli, and Michele Lanza. Using Discord conversations as program comprehension aid. In Proceedings of ICPC 2022 (International Conference on Program Comprehension), pages 597-601. ACM, 2022. Google Scholar
  51. Marco Raglianti, Csaba Nagy, Roberto Minelli, Bin Lin, and Michele Lanza. Replication package. URL: https://figshare.com/s/33c8af534dba61d72c41.
  52. Reddit. Reddit. URL: https://www.reddit.com/.
  53. Lionel P Robert and Alan R Dennis. Paradox of richness: A cognitive model of media choice. IEEE Transactions on Professional Communication, 48(1):10-21, 2005. Google Scholar
  54. Martin P Robillard and Robert DeLine. A field study of API learning obstacles. Empirical Software Engineering, 16(6):703-732, 2011. Google Scholar
  55. Martin P. Robillard, Andrian Marcus, Christoph Treude, Gabriele Bavota, Oscar Chaparro, Neil Ernst, Marco Aurélio Gerosa, Michael Godfrey, Michele Lanza, Mario Linares-Vásquez, Gail C. Murphy, Laura Moreno, David Shepherd, and Edmund Wong. On-demand developer documentation. In Proceedings of ICSME 2017 (International Conference on Software Maintenance and Evolution), pages 479-483. IEEE, 2017. Google Scholar
  56. Hareem Sahar, Abram Hindle, and Cor-Paul Bezemer. How are issue reports discussed in Gitter chat rooms? Journal of Systems and Software, 172:110852, 2021. Google Scholar
  57. Benjamin Saunders, Julius Sim, Tom Kingstone, Shula Baker, Jackie Waterfield, Bernadette Bartlam, Heather Burroughs, and Clare Jinks. Saturation in qualitative research: Exploring its conceptualization and operationalization. Quality & Quantity, 52(4):1893-1907, 2018. Google Scholar
  58. Lin Shi, Xiao Chen, Ye Yang, Hanzhi Jiang, Ziyou Jiang, Nan Niu, and Qing Wang. A first look at developers' live chat on Gitter. In Proceedings of ESEC/FSE 2021 (European Software Engineering Conference and Symposium on the Foundations of Software Engineering), pages 391-403. ACM, 2021. Google Scholar
  59. Emad Shihab, Zhen Ming Jiang, and Ahmed E Hassan. On the use of internet relay chat (IRC) meetings by developers of the GNOME GTK+ project. In Proceedings of MSR 2009 (Working Conference on Mining Software Repositories), pages 107-110. IEEE, 2009. Google Scholar
  60. Slack Technologies. Slack. URL: https://slack.com/.
  61. Ian Sommerville. Software Engineering. Pearson, 10th edition, 2015. Google Scholar
  62. Sonatype. Maven Central Repository. URL: https://central.sonatype.dev/.
  63. Donna Spencer. Card Sorting: Designing Usable Categories. Rosenfeld Media, 2009. Google Scholar
  64. Stack Exchange, Inc. Stack Overflow. URL: https://stackoverflow.com/.
  65. Margaret-Anne Storey, Alexey Zagalsky, Fernando Figueira Filho, Leif Singer, and Daniel M. German. How social and communication channels shape and challenge a participatory culture in software development. IEEE Transactions on Software Engineering, 43(2):185-204, 2017. Google Scholar
  66. Viktoria Stray and Nils Brede Moe. Understanding coordination in global software engineering: A mixed-methods study on the use of meetings and Slack. Journal of Systems and Software, 170:110717, 2020. Google Scholar
  67. Keerthana Muthu Subash, Lakshmi Prasanna Kumar, Sri Lakshmi Vadlamani, Preetha Chatterjee, and Olga Baysal. DISCO: A dataset of Discord chat conversations for software engineering research. In Proceedings of MSR 2022 (International Conference on Mining Software Repositories), pages 227-231. IEEE/ACM, 2022. Google Scholar
  68. Jirateep Tantisuwankul, Yusuf Sulistyo Nugroho, Raula Gaikovina Kula, Hideaki Hata, Arnon Rungsawang, Pattara Leelaprute, and Kenichi Matsumoto. A topological analysis of communication channels for knowledge sharing in contemporary GitHub projects. Journal of Systems and Software, 158:110416, 2019. Google Scholar
  69. Telegram. Telegram. URL: https://telegram.org/.
  70. The Matrix.org Foundation C.I.C. Matrix. URL: https://matrix.org/.
  71. Mike Thelwall and Liwen Vaughan. A fair history of the web? Examining country balance in the Internet Archive. Library & Information Science Research, 26(2):162-176, 2004. Google Scholar
  72. Yuan Tian, Palakorn Achananuparp, Ibrahim Nelman Lubis, David Lo, and Ee-Peng Lim. What does software engineering community microblog about? In Proceedings of MSR 2012 (Working Conference on Mining Software Repositories), pages 247-250. IEEE, 2012. Google Scholar
  73. Travis CI. Travis CI. URL: https://www.travis-ci.com/.
  74. Christoph Treude and Margaret-Anne Storey. Effective communication of software development knowledge through community portals. In Proceedings of ESEC/FSE 2011 (European Software Engineering Conference and Symposium on the Foundations of Software Engineering), pages 91-101. ACM, 2011. Google Scholar
  75. Twitter, Inc. Twitter. URL: https://twitter.com/.
  76. Jed R Wood and Larry E Wood. Card sorting: Current practices and beyond. Journal of Usability Studies, 4(1):1-6, 2008. Google Scholar
  77. Zhou Yang, Chenyu Wang, Jieke Shi, Thong Hoang, Pavneet Kochhar, Qinghua Lu, Zhenchang Xing, and David Lo. What do users ask in open-source AI repositories? An empirical study of GitHub issues. arXiv preprint arXiv:2303.09795, 2023. Google Scholar
  78. Liguo Yu, Srini Ramaswamy, Alok Mishra, and Deepti Mishra. Communications in global software development: An empirical study using GTK+ OSS repository. In Proceedings of OTM 2011 (On the Move to Meaningful Internet Systems), pages 218-227. Springer, 2011. Google Scholar
  79. Junji Zhi, Vahid Garousi-Yusifoğlu, Bo Sun, Golara Garousi, Shawn Shahnewaz, and Guenther Ruhe. Cost, benefits and quality of software development documentation: A systematic mapping. Journal of Systems and Software, 99:175-198, 2015. Google Scholar
  80. Carlos Zimmerle, Kiev Gama, Fernando Castor, and José Murilo Mota Filho. Mining the usage of reactive programming APIs: A study on GitHub and Stack Overflow. In Proceedings of MSR 2022 (International Conference on Mining Software Repositories), pages 203-214. ACM, 2022. Google Scholar
  81. Zyte. Scrapy. URL: https://scrapy.org.
Questions / Remarks / Feedback
X

Feedback for Dagstuhl Publishing


Thanks for your feedback!

Feedback submitted

Could not send message

Please try again later or send an E-mail
© 2023-2024 Schloss Dagstuhl – LZI GmbH Imprint Privacy Contact