Change search
CiteExportLink to record
Permanent link

Direct link
Cite
Citation style
  • apa
  • ieee
  • modern-language-association-8th-edition
  • vancouver
  • Other style
More styles
Language
  • de-DE
  • en-GB
  • en-US
  • fi-FI
  • nn-NO
  • nn-NB
  • sv-SE
  • Other locale
More languages
Output format
  • html
  • text
  • asciidoc
  • rtf
Towards identifying and minimizing customer-facing documentation debt
Blekinge Institute of Technology, Faculty of Computing, Department of Software Engineering. Ericsson AB, Karlskrona, Sweden.ORCID iD: 0000-0002-5027-9316
Blekinge Institute of Technology, Faculty of Computing, Department of Software Engineering.ORCID iD: 0000-0003-4118-0952
Blekinge Institute of Technology, Faculty of Computing, Department of Software Engineering.ORCID iD: 0000-0003-3567-9300
2023 (English)In: Proceedings - 2023 ACM/IEEE International Conference on Technical Debt, TechDebt 2023, Institute of Electrical and Electronics Engineers (IEEE), 2023, p. 72-81Conference paper, Published paper (Refereed)
Abstract [en]

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.

Place, publisher, year, edition, pages
Institute of Electrical and Electronics Engineers (IEEE), 2023. p. 72-81
Keywords [en]
Documentation Debt, Technical Debt, Automation
National Category
Software Engineering
Research subject
Software Engineering
Identifiers
URN: urn:nbn:se:bth-24654DOI: 10.1109/TechDebt59074.2023.00015ISI: 001051233000009Scopus ID: 2-s2.0-85169420574OAI: oai:DiVA.org:bth-24654DiVA, id: diva2:1760479
Conference
6th International Conference on Technical Debt, TechDebt 2023, Melbourne, Australia, 14 May 2023 through 15 May 2023
Available from: 2023-05-30 Created: 2023-05-30 Last updated: 2024-10-10Bibliographically approved
In thesis
1. On Identifying Technical Debt using Bug Reports in Practice
Open this publication in new window or tab >>On Identifying Technical Debt using Bug Reports in Practice
2023 (English)Licentiate thesis, comprehensive summary (Other academic)
Abstract [en]

Context: In an era where every industry is impacted by software, it is vital to keep software costs under control for organizations to be competitive. A key factor contributing to software costs is software maintenance where a significant proportion is utilized to deal with different types of technical debt. Technical debt is a metaphor used to describe the cost of taking shortcuts or sub-optimal design and implementation that compromises the software quality. Similar to financial debt, technical debt needs to be paid off in the future.

Objective: To be in control of technical debt related costs, organizations need to identify technical debt types and quantify them to introduce solutions and prioritize repayment strategies. However, the invisible nature of technical debt makes its identification challenging in practice. Our aim is to find pragmatic ways to identify technical debt in practice, that can be supported by evidence. Once technical debt types that are significant have been identified, we aim to propose suggestions to mitigate them.

Method: We used design science as a methodological framework to iteratively improve the technical debt identification methods. We utilized bug reports, which are artifacts produced by software engineers during the development and operation of the software system  as the data source for technical debt identification. Software defects reported through bug reports are considered as one of the key external quality attributes of a software system  which supports us in our evidence based approach. Throughout the design science iterations, we used the following research methods: case study and sample study.

Results: We produced three design artifacts that support technical debt identification. The first artifact is a systematic process to identify architectural technical debt from bug reports. The second is an automated bug analysis and a visualization tool to support our research as well as to support practitioners to identify components with hot spots in relation to the number of defects. The third is a method for identifying documentation debt from bug reports.

Conclusion: Based on the findings from this thesis, we demonstrated that bug reports can be utilized as a data source to identify technical debt in practice by identifying two types of technical debt; architectural technical debt and documentation debt. Compared to the identification of documentation debt, architectural technical debt identification still remains challenging due to the abstract nature of the architecture and its boundaries. Therefore, our future work will focus on evaluating the impact of reducing the sources of documentation debt on the frequency of bug reports and overall project cost.

Place, publisher, year, edition, pages
Karlskrona: Blekinge Tekniska Högskola, 2023
Series
Blekinge Institute of Technology Licentiate Dissertation Series, ISSN 1650-2140 ; 2023:06
Keywords
Technical Debt, Architectural Technical Debt, Documentation Debt, Empirical Software Engineering, Design Science
National Category
Software Engineering
Research subject
Software Engineering
Identifiers
urn:nbn:se:bth-24462 (URN)978-91-7295-458-8 (ISBN)
Presentation
2023-06-12, Karlskrona, 09:00 (English)
Opponent
Supervisors
Available from: 2023-04-24 Created: 2023-04-24 Last updated: 2023-06-02Bibliographically approved

Open Access in DiVA

fulltext(635 kB)117 downloads
File information
File name FULLTEXT01.pdfFile size 635 kBChecksum SHA-512
560f56e2f2292fb8f6120d593b1f26c5338482d58940939f65b90c3ec66ee322d0aab1651a2a52d2307f87ef85da11d9a7d9b6cc1e3ea2d47dd29dbd41994bef
Type fulltextMimetype application/pdf

Other links

Publisher's full textScopus

Authority records

Silva, LakmalUnterkalmsteiner, MichaelWnuk, Krzysztof

Search in DiVA

By author/editor
Silva, LakmalUnterkalmsteiner, MichaelWnuk, Krzysztof
By organisation
Department of Software Engineering
Software Engineering

Search outside of DiVA

GoogleGoogle Scholar
Total: 117 downloads
The number of downloads is the sum of all downloads of full texts. It may include eg previous versions that are now no longer available

doi
urn-nbn

Altmetric score

doi
urn-nbn
Total: 204 hits
CiteExportLink to record
Permanent link

Direct link
Cite
Citation style
  • apa
  • ieee
  • modern-language-association-8th-edition
  • vancouver
  • Other style
More styles
Language
  • de-DE
  • en-GB
  • en-US
  • fi-FI
  • nn-NO
  • nn-NB
  • sv-SE
  • Other locale
More languages
Output format
  • html
  • text
  • asciidoc
  • rtf