Project

Back to overview

UpSoDoc - Semi-Automatic Update of Software Documentation during Software Evolution

English title UpSoDoc - Semi-Automatic Update of Software Documentation during Software Evolution
Applicant Glinz Martin
Number 157004
Funding scheme Project funding (Div. I-III)
Research institution Institut für Informatik Universität Zürich
Institution of higher education University of Zurich - ZH
Main discipline Information Technology
Start/End 01.04.2015 - 31.03.2019
Approved amount 234'054.00
Show all

Keywords (4)

Software traceability; Artifact alignment; Software evolution; Documentation update

Lay Summary (German)

Lead
Das Wissen über Softwaresysteme ist oft über viele Artefakte verstreut. Beispiele für solche Artefakte sind die Anforderungsspezifikation, Software-Architekturdokumente und der eigentlichen Quellcode. Das in diesen Artefakten steckende Wissen sollte erhalten bleiben, wenn ein System aufgrund veränderter Umgebungsbedingungen oder Bedürfnisse geändert wird. In der Praxis wird jedoch häufig nur der Quellcode geändert, während die Aktualisierung der übrigen relevanten Artefakte aus Kosten- und Zeitgründen unterbleibt. Damit wird die Dokumentation auf die Dauer wertlos und das darin enthaltene Wissen geht verloren.
Lay summary

In diesem Projekt werden neue Methoden erforscht, die das Problem von veralteter Softwaredokumentation adressieren und minimieren. Dies beinhaltet die Nutzung von Informationen zur Verfolgbarkeit von Anforderungen sowie weiterer Information, welche Abhängigkeiten zwischen Artefakten aufzeigt. Basierend auf dieser Information werden automatisch Hinweise generiert, die den Softwareingenieuren aufzeigen, welche Informationen in anderen Artefakten entsprechend den neusten Quellcodeänderungen zu aktualisieren sind. Somit wird sichergestellt, dass das dokumentierte Wissen über ein Softwaresystem nach jedem Evolutionsschritt auf dem neusten Stand bleibt.

Die Resultate dieses Forschungsprojekts werden die wissenschaftlichen Erkenntnisse, wie die verschiedenen Artefakte aktuell gehalten werden können, erweitern. Wir erwarten neue Erkenntnisse in den Bereichen Verfolgbarkeit von Anforderungen, Softwaredokumentation und Softwareevolution. Neben neuen wissenschaftlichen Erkenntnissen ist das geplante Forschungsvorhaben auch für die Praxis relevant. Die aus dem Projekt resultierenden Ansätze haben das Ziel, die heutige Softwareentwicklungspraxis zu verbessern, indem der Aufwand für die Aktualisierung von Softwaredokumentationen minimiert wird. Dadurch werden Softwareingenieure motiviert, Aktualisierungen kontinuierlich durchzuführen.

 

Direct link to Lay Summary Last update: 16.03.2015

Lay Summary (English)

Lead
The knowledge about a software system is scattered through several artifacts, such as the requirements specification, the software architecture and the source code. This knowledge should be preserved when the system is changed and adapted due to changes in its environment or changed needs of its stakeholders. Nevertheless, due to time and cost constrains, developers often apply the changes to the source code only and neglect updating the other artifacts. Thus, these artifacts eventually become useless and the knowledge contained in them is lost.
Lay summary

In this project, we aim at investigating new methods to address the problem of outdated software documentation.  For this, we will use traceability links and other information about the relations between the different artifacts to provide maintainers with automatically generated guidance about what to change in the documentation after each evolutionary step.

The outcome of this research will extend the scientific knowledge about how to keep the documentation of a software system up-to-date when the system evolves. We expect new findings in the fields of software traceability, software documentation and software evolution. Besides advancing scientific knowledge, our research is also relevant for industrial practice. In fact, the investigated approaches should improve the current software development practice, by reducing the effort needed for keeping software documentation up-to-date, thus encouraging maintainers to perform documentation updates regularly.

 

Direct link to Lay Summary Last update: 16.03.2015

Responsible applicant and co-applicants

Employees

Name Institute

Publications

Publication
GuideGen: An approach for keeping requirements and acceptance tests aligned via automatically generated guidance
Hotomski Sofija, Glinz Martin (2019), GuideGen: An approach for keeping requirements and acceptance tests aligned via automatically generated guidance, in Information and Software Technology, 110, 17-38.
A Qualitative Study on using GuideGen to Keep Requirements and Acceptance Tests Aligned
Hotomski Sofija, Glinz Martin (2018), A Qualitative Study on using GuideGen to Keep Requirements and Acceptance Tests Aligned, in 2018 IEEE 26th International Requirements Engineering Conference (RE), Banff, ABIEEE Computer Society, Los Alamitos, CA..
GuideGen – A Tool for Keeping Requirements and Acceptance Tests Aligned
Hotomski Sofija, Glinz Martin (2018), GuideGen – A Tool for Keeping Requirements and Acceptance Tests Aligned, in the 40th International Conference, Gothenburg, SwedenACM, New York NY.
Keeping Evolving Requirements and Acceptance Tests Aligned with Automatically Generated Guidance
Hotomski Sofija, Ben Charrada Eya, Glinz Martin (2018), Keeping Evolving Requirements and Acceptance Tests Aligned with Automatically Generated Guidance, in Requirements Engineering: Foundation for Software Quality (REFSQ 2018), Utrecht, The NetherlandsSpringer International Publishing, Cham.
Aligning Requirements and Acceptance Tests via Automatically Generated Guidance
Hotomski Sofija, Charrada Eya Ben, Glinz Martin (2017), Aligning Requirements and Acceptance Tests via Automatically Generated Guidance, in 2017 IEEE 25th International Requirements Engineering Conference Workshops (REW), Lisbon, PortugalIEEE Computer Society, Los Alamitos, CA..
An Exploratory Study on Handling Requirements and Acceptance Test Documentation in Industry
Sofija Hotomski, Eya Ben Charrada, Martin Glinz (2016), An Exploratory Study on Handling Requirements and Acceptance Test Documentation in Industry, in 24th IEEE International Requirements Engineering Conference.

Collaboration

Group / person Country
Types of collaboration
No specific institution, see below. Switzerland (Europe)
- in-depth/constructive exchanges on approaches, methods or results

Awards

Title Year
Best paper award for publication "Keeping Evolving Requirements and Acceptance Tests Aligned with Automatically Generated Guidance" at REFSQ2018 in Utrecht, The Netherlands. 2018

Abstract

The knowledge about a software system is scattered through several artifacts, which together constitute the system's documentation. Key artifacts containing such knowledge include the requirements specification, software architecture and design, source code, tests, and user manual. Preserving the knowledge contained in all these artifacts is crucial for ensuring a high quality software system that can be easily maintained and extended. For example, if a requirements specification has become obsolete, the ability to trace system features to the rationale why these features have been implemented is lost. Similarly, when the architecture document becomes obsolete, the knowledge about design decisions and why they have been taken is lost. This is becoming even more crucial nowadays, as systems are continuously evolved and tailored to individual customers' needs.If software artifacts are not maintained and updated when a system evolves, they progressively become outdated and useless. Nevertheless, due to time and cost constrains, developers often neglect updating the entire documentation and apply the changes to the source code only. This negatively affects a system's maintainability and increases the cost of adapting a system to changes in its environment and to new or changed needs of its users.The goal of this project is to investigate new methods to address the problem of outdated software documentation. We will explore new techniques that merge information from different artifacts to generate precise traceability links between the software artifacts. We will also develop an approach that automates parts of the change propagation task between software artifacts. The approach will be based on an analysis of the relations that exist between different types of software artifacts at the evolution stage.The outcome of this research will extend the scientific knowledge in the fields of software traceability, software documentation and software evolution. It will also improve current software development practice by reducing the effort needed for keeping software documentation up-to-date, thus encouraging maintainers to perform documentation updates regularly.
-