Topology of the Documentation Landscape

Raglianti, Marco

doi:10.1109/icse-companion55297.2022.9793831

Cited by 2 publications

(4 citation statements)

References 37 publications

Supporting

Mentioning

Contrasting

Order By: Relevance

“…Recent studies have also proposed utilizing diverse, novel sources like developers' blog posts, micro-blogging on platforms like Twitter, and rich media instant messaging to augment traditional software documentation. 69 Aghajani et al 65 highlight issues in software documentation, such as inconsistency and outdatedness, which can be mitigated through automated generation techniques like program analysis, 70 source code summarization, 71 and automatic comment updating. 72 Although these methods offer insights into the broader realm of software documentation enrichment, they often possess distinct focuses and are not primarily aimed at documentation enhancement.…”

Section: Enrichment Of Software Documentationmentioning

confidence: 99%

“…Ding et al 68 further explore knowledge‐based approaches in software documentation, focusing on architectural design. Recent studies have also proposed utilizing diverse, novel sources like developers' blog posts, micro‐blogging on platforms like Twitter, and rich media instant messaging to augment traditional software documentation 69 . Aghajani et al 65 highlight issues in software documentation, such as inconsistency and outdatedness, which can be mitigated through automated generation techniques like program analysis, 70 source code summarization, 71 and automatic comment updating 72 .…”

Section: Related Workmentioning

confidence: 99%

See 1 more Smart Citation

Richen: Automated enrichment of Git documentation with usage examples and scenarios

Shen,

Yang,

Jia

et al. 2024

J Software Evolu Process

View full text Add to dashboard Cite

As the predominant modern version control system, Git has become an indispensable tool for both commercial and open‐source software projects. It substantially improves software development effectiveness and efficiency through its distributed version control system, fostering seamless collaboration among teams and across locations. However, research has found that many developers have doubts about using Git commands, while the official Git documentation is rather scanty, that is, lacking sufficient explanations and examples. To help developers learn and use Git commands, we propose the first approach (Richen) for enriching Git documentation with usage examples and scenarios by leveraging crowd knowledge from Stack Overflow. Richen retrieves Git‐related posts from Stack Overflow, extracts relevant Q&A pairs, and selects representative command usages, including usage examples and scenarios, for different Git commands. Experimental results have shown that Richen can extract informative and concise command usages for Git commands. Compared with alternative methods adapted from API usage mining, the command usages obtained by Richen have significant advantages in terms of relevance, readability, and usability. Furthermore, we have shown through an empirical study that the command usages extracted by Richen can better help developers complete Git command‐related tasks.

show abstract

Section: Enrichment Of Software Documentationmentioning

confidence: 99%

Section: Related Workmentioning

confidence: 99%

Richen: Automated enrichment of Git documentation with usage examples and scenarios

Shen,

Yang,

Jia

et al. 2024

J Software Evolu Process

View full text Add to dashboard Cite

show abstract

“…However, most of these solutions are targeting developer documentation, which is different to customer-facing documentation in terms of the target audience, the documentation content and how they have been produced. For instance, developer documentation is internal raw documentation whereas customer-facing documentation is external and formatted to be used by the external users of the system [26]. Developer documentation is usually maintained by developers whereas customer-facing documentation is written and maintained by technical writers [26] that follows different tools and processes compared to loosely managed developer documentation.…”

Section: Related Workmentioning

confidence: 99%

“…For instance, developer documentation is internal raw documentation whereas customer-facing documentation is external and formatted to be used by the external users of the system [26]. Developer documentation is usually maintained by developers whereas customer-facing documentation is written and maintained by technical writers [26] that follows different tools and processes compared to loosely managed developer documentation.…”

Section: Related Workmentioning

confidence: 99%

Towards identifying and minimizing customer-facing documentation debt

Silva

Unterkalmsteiner

Wnuk

2023

2023 ACM/IEEE International Conference on Technical Debt (TechDebt)

View full text Add to dashboard Cite

Background: Software documentation often struggles to catch up with the pace of software evolution. The lack of correct, complete, and up-to-date documentation results in an increasing number of documentation defects which could introduce delays in integrating software systems. In our previous study on a bug analysis tool called MultiDimEr, we provided evidence that documentation-related defects contribute to a significant number of bug reports. Aims: First, we want to identify documentation defect types contributing to documentation defects and thereby identifying documentation debt. Secondly, we aim to find pragmatic solutions to minimize most common documentation defects to pay off the documentation debt in the long run. Method: We investigated documentation defects related to an industrial software system. First, we looked at the types of different documentation and associated bug reports. We categorized the defects according to an existing documentation defect taxonomy. Results: Based on a sample of 101 defects, we found that a majority of defects are caused by documentation defects falling into the Information Content (What) category (86). Within this category, the documentation defect types Erroneous code examples (23), Missing documentation (35), and Outdated content (19) contributed to most of the documentation defects. We propose to adapt two solutions to mitigate these types of documentation defects. Conclusions: In practice, documentation debt can easily go undetected since a large share of resources and focus is dedicated to deliver high-quality software. This study provides evidence that documentation debt can contribute to increase in maintenance costs due to the number of documentation defects. We suggest to adapt two main solutions to tackle documentation debt by implementing (i) Dynamic Documentation Generation (DDG) and/or (ii) Automated Documentation Testing (ADT), which are both based on defining a single and robust information source for documentation.

show abstract

Topology of the Documentation Landscape

Cited by 2 publications

References 37 publications

Richen: Automated enrichment of Git documentation with usage examples and scenarios

Richen: Automated enrichment of Git documentation with usage examples and scenarios

Towards identifying and minimizing customer-facing documentation debt

Contact Info

Product

Resources

About