R is a package-based programming ecosystem that provides an easy way to install third-party code, datasets, and examples. Thus, R developers rely heavily on the documentation of the packages they import to use them correctly and accurately. This documentation is often written using Roxygen, equivalent to Java’s well-known Javadoc. This two-part study provides the first analysis in this area. First, 379 systematically-selected, open-source R packages were mined and analysed to address the quality of their documentation in terms of presence, distribution, and completeness to identify potential sources of documentation debt of technical debt that describes problems in the documentation. Second, a survey addressed how R package developers perceive documentation and face its challenges (with a response rate of 10.04%). Results show that incomplete documentation is the most common smell, with several cases of incorrect use of the Roxygen utilities. Unlike in traditional API documentation, developers do not focus on how behaviour is implemented but on common use cases and parameter documentation. Respondents considered the examples section the most useful, and commonly perceived challenges were unexplained examples, ambiguity, incompleteness and fragmented information.

Dr Vidoni is an academic (Lecturer, eq. to Assistant Professor) at the Australian National University in the School of Computing. She has ongoing domestic and international collaborations, the latter with Canada and Germany. Dr Vidoni’s main research interests are mining software repositories, technical debt and software development; empirical software engineering when applied to data science and scientific software.

She graduated from Universidad Tecnologica Nacional (UTN) as an Information Systems Engineer. Years later, she received her PhD on the same institution, with the maximum qualification. She funded R-Ladies Santa Fe in 2018, and in 2019 moved to Australia to further her research career. Since 2018, she is also Associate Editor for rOpenSci, and Editorial Board member of Information and Software Technology.