License: Creative Commons Attribution 4.0 International license (CC BY 4.0)
When quoting this document, please refer to the following
DOI: 10.4230/LIPIcs.ECOOP.2023.43
URN: urn:nbn:de:0030-drops-182369
URL: http://dagstuhl.sunsite.rwth-aachen.de/volltexte/2023/18236/
Go to the corresponding LIPIcs Volume Portal

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

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

pdf-format:
LIPIcs-ECOOP-2023-43.pdf (3 MB)

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.

BibTeX - Entry

@InProceedings{raglianti_et_al:LIPIcs.ECOOP.2023.43,
  author =	{Raglianti, Marco and Nagy, Csaba and Minelli, Roberto and Lin, Bin and Lanza, Michele},
  title =	{{On the Rise of Modern Software Documentation}},
  booktitle =	{37th European Conference on Object-Oriented Programming (ECOOP 2023)},
  pages =	{43:1--43:24},
  series =	{Leibniz International Proceedings in Informatics (LIPIcs)},
  ISBN =	{978-3-95977-281-5},
  ISSN =	{1868-8969},
  year =	{2023},
  volume =	{263},
  editor =	{Ali, Karim and Salvaneschi, Guido},
  publisher =	{Schloss Dagstuhl -- Leibniz-Zentrum f{\"u}r Informatik},
  address =	{Dagstuhl, Germany},
  URL =		{https://drops.dagstuhl.de/opus/volltexte/2023/18236},
  URN =		{urn:nbn:de:0030-drops-182369},
  doi =		{10.4230/LIPIcs.ECOOP.2023.43},
  annote =	{Keywords: software documentation landscape, GitHub README, instant messaging}
}

Keywords: software documentation landscape, GitHub README, instant messaging
Collection: 37th European Conference on Object-Oriented Programming (ECOOP 2023)
Issue Date: 2023
Date of publication: 11.07.2023
Supplementary Material: Software: https://figshare.com/s/33c8af534dba61d72c41

DROPS-Home | Fulltext Search | Imprint | Privacy Published by LZI