Software Documentation

Online resources of formal and informal documentation-such as reference manuals, forum discussions and tutorials-have become an asset to software developers, as they allow them to tackle problems and to learn about new tools, libraries, and technologies. This study investigates to what extent and for which purpose developers refer to external online resources when they contribute changes to a repository by raising a pull request. Our study involved (i) a quantitative analysis of over 150k URLs occurring in pull requests posted in GitHub, (ii) a manual coding of the kinds of software evolution activities performed in commits related to a statistically significant sample of 2,130 pull requests referencing external documentation resources, (iii) a survey with 69 participants, who provided feedback on how they use online resources and how they refer to them when filing a pull request. Results of the study indicate that, on the one hand, developers find external resources useful to learn something new or to solve specific problems, and they perceive useful referring such resources to better document changes. On the other hand, both interviews and repository mining suggest that external resources are still rarely referred in document changes.

Most software engineering research focuses its analyses on source code, because correct, well designed, and efficient program code is the desired end output of software development. Nevertheless, source code is not the only constituent of software systems: Programs also comprise other types of artifacts, such as documentation, build system and configuration files, and graphics. These non-code artifacts only recently got the attention of researchers and are not yet investigated as a whole, but separately and with very specific aims. By taking a quantitative perspective, we look into non-code software artifacts to measure their role in software systems. We analyze 35 mature open-source software systems and we address exploratory questions such as: How many non-code software artifacts do software systems contain? How do they relate to source code? How much effort is put into producing and maintaining them? Our results show that a significant portion of systems is made of non-code artifacts, and that programmers spend a relevant part of their effort on non-code artifacts during the development process. Our analysis opens questions for future investigations.