Software Documentation Issues Unveiled

Aghajani, Emad; Nagy, Csaba; Vega-Márquez, Olga Lucero; Linares‐Vásquez, Mario; Moreno, Laura; Bavota, Gabriele; Lanza, Michele

doi:10.1109/icse.2019.00122

Cited by 131 publications

(108 citation statements)

References 56 publications

Supporting

Mentioning

104

Contrasting

Unclassified

Order By: Relevance

“…Although, in principle, this is against the notion of open coding, little is known about general-type build fixing and the granularity of previous error category is too coarse in our study. Hence, to avoid the number of labels from growing excessively, following previous studies [4,16], we adopt the compromise without introducing substantial bias. In this process, the conflict ratio between two authors is 25.65%.…”

Section: Manual Labellingmentioning

confidence: 99%

“…Hence, build script generation or completion tools are helpful for developers in programming build scripts, where modern code generation techniques [11,15,31] may be adopted since build scripts are often semi-structured and most build tasks can be specified concisely. Furthermore, we observe that developers complain about documents and tutorials in their SO posts (e.g., "Neither the documentation had any sort of straightforward example..." [1]), indicating that the completeness, usability, and readability of documents in third-party plugins, dependencies, and build tools should be improved [4]. In addition, to a certain extent, the how-to topics with high frequency imply the build components that developers are unfamiliar with, which are vulnerable and subject to introducing defects in the further build script evolution.…”

Section: Manual Labellingmentioning

confidence: 99%

See 1 more Smart Citation

Understanding build issue resolution in practice: symptoms and fix patterns

Lou

Chen

Cao

et al. 2020

Proceedings of the 28th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Softw

View full text Add to dashboard Cite

Build systems are essential for modern software maintenance and development, while build failures occur frequently across software systems, inducing non-negligible costs in development activities. Build failure resolution is a challenging problem and multiple studies have demonstrated that developers spend non-trivial time in resolving encountered build failures; to relieve manual efforts, automated resolution techniques are emerging recently, which are promising but still limitedly effective. Understanding how build failures are resolved in practice can provide guidelines for both developers and researchers on build issue resolution. Therefore, this work presents a comprehensive study of fix patterns in practical build failures. Specifically, we study 1,080 build issues of three popular build systems Maven, Ant, and Gradle from Stack Overflow, construct a fine-granularity taxonomy of 50 categories regarding to the failure symptoms, and summarize the fix patterns for different failure types. Our key findings reveal that build issues stretch over a wide spectrum of symptoms; 67.96% of the build issues are fixed by modifying the build script code related to plugins and dependencies; and there are 20 symptom categories, more than half of whose build issues can be fixed by specific patterns. Furthermore, we also address the challenges in applying non-intuitive or simplistic fix patterns for developers. CCS CONCEPTS • Software and its engineering → Software testing and debugging.

show abstract

Section: Manual Labellingmentioning

confidence: 99%

Section: Manual Labellingmentioning

confidence: 99%

Understanding build issue resolution in practice: symptoms and fix patterns

Lou

Chen

Cao

et al. 2020

Proceedings of the 28th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Softw

View full text Add to dashboard Cite

show abstract

“…High-quality software documentation is crucial for software development, comprehension, and maintenance, but the ways that documentation can suffer poor quality are numerous. For example, Aghajani et al [1] have designed a taxonomy of 162 documentation issue types, covering information content, presentation, processrelated matters, and tool-related matters. Additionally, because software documentation is written in informal natural language which is inherently ambiguous, imprecise, unstructured, and complex in syntax and semantics, its quality can often only be evaluated 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.…”

Section: Introductionmentioning

confidence: 99%

Beyond accuracy: assessing software documentation quality

Middleton

Atapattu

2020

Proceedings of the 28th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Softw

View full text Add to dashboard Cite

Good software documentation encourages good software engineering, but the meaning of "good" documentation is vaguely defined in the software engineering literature. To clarify this ambiguity, we draw on work from the data and information quality community to propose a framework that decomposes documentation quality into ten dimensions of structure, content, and style. To demonstrate its application, we recruited technical editors to apply the framework when evaluating examples from several genres of software documentation. We summarise their assessments-for example, reference documentation and README files excel in quality whereas blog articles have more problems-and we describe our vision for reasoning about software documentation quality and for the expansion and potential of a unified quality framework. CCS CONCEPTS • Software and its engineering → Documentation; • Social and professional topics → Quality assurance.

show abstract

“…Software documentation is considered to be one of the most important aspects in software development [15]. It facilitates better understanding of software and helps in many phases of software development and maintenance [1,3]. Many software projects are available on open source code sharing platforms such as Github 1 , BitBucket 2 , Sourceforge 3 and so on.…”

Section: Introductionmentioning

confidence: 99%

“…Considering its advantages, software development is being accompanied by documentation, written by various team members during the software development process [13]. However, researchers have observed that this documentation does not evolve along with code, and does not suffice to the developer needs in many scenarios [1]. Documentation for a software project is present across various files in the project such as readme files, source code files, uml files and so on [4,10].…”

Section: Introductionmentioning

confidence: 99%

Software documentation and augmented reality: love or arranged marriage?

Chimalakonda

Venigalla

2020

Proceedings of the 28th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Softw

View full text Add to dashboard Cite

There is a significant rise in the availability, development and size of software projects in the present day. Many open source projects are reused or updated for various purposes that include fixing bugs in existing projects, development and maintenance of project extensions. Developers who interact with the projects might require documentation for better comprehension of the project and to develop extensions. Most of the software projects currently do not have sufficient documentation or it is not updated along with the project. If some projects have reasonably sufficient documentation, it is usually difficult to comprehend it either for maintenance or for reuse purposes. Considering the usefulness of Augmented Reality (AR) towards comprehension, we propose the vision of integrating the domains of augmented reality and software documentation, and specifically, visualization of software documentation using AR. In this paper, we present some of the directions that could be explored towards this vision and also present an example visualization scenario for API documentation using neural system metaphor. We see this paper as a basis for the future research direction of leveraging AR towards making documentation as a primary artifact in the software development process. CCS CONCEPTS • Software and its engineering → Documentation; Design languages; Unified Modeling Language (UML).

show abstract

Software Documentation Issues Unveiled

Cited by 131 publications

References 56 publications

Understanding build issue resolution in practice: symptoms and fix patterns

Understanding build issue resolution in practice: symptoms and fix patterns

Beyond accuracy: assessing software documentation quality

Software documentation and augmented reality: love or arranged marriage?

Contact Info

Product

Resources

About