Supporting the documentation of architectural decision records in IDEs : a VS code plugin for the ADR manager

Abstract

Software architecture is largely shaped by decisions made during the software development life cycle. These architectural decisions contain information about the underlying architecture that is relevant for creating a unified view of the architecture across all stakeholders of the software project. Disregarding the documentation of architectural decisions leads to a multitude of problems during the maintenance of the software. One way of capturing architectural decisions along with their rationale is using so-called architectural decision records (ADRs). Tools for managing ADRs already exist, but they often operate in a context that feels unfamiliar to software developers or requires them to switch to a different tool. This thesis explores the possibility of providing ADR tooling as an IDE plugin, making ADR management features conveniently available for developers. The result of the research is the ADR Manager extension for the Visual Studio Code IDE, available on the Visual Studio Code Marketplace. This extension is based on the web-based tool with the same name and provides features for creating, editing, and managing ADRs on a local repository in a Markdown format. In addition to providing two form-based ADR editors with varying levels of detail, the extension enhances the functionality of the raw Markdown editor of the IDE by providing linting support and quick insertion of ADR templates in the form of snippets. In an empirical user study with seven software professionals, the ADR Manager extension received resounding feedback from evaluation participants regarding its usability in the context of Visual Studio Code. The participants praised the simple yet effective extension functionality, stating that it fits nicely in the IDE environment. On the other hand, they wished that the extension was at times more concise in communicating which inputs are available to the user and how the extension expects the user to enter them such that they receive their desired result. Still being a prototype, there are multiple ways the extension can be improved in the future. Examples include enhancing existing functionality, extending the functionality to appeal to more users, or implementing the support for more ADR formats.

Die Softwarearchitektur wird weitgehend durch Entscheidungen geprägt, die während des Lebenszyklus der Softwareentwicklung getroffen werden. Diese Architekturentscheidungen enthalten Informationen über die zugrundeliegende Architektur, die für die Schaffung einer einheitlichen Sicht auf die Architektur für alle Beteiligten des Softwareprojekts von Bedeutung sind. Die Vernachlässigung der Dokumentation von Architekturentscheidungen führt zu einer Vielzahl von Problemen bei der Wartung der Software. Eine Möglichkeit, Architekturentscheidungen zusammen mit ihrer Begründung festzuhalten, ist die Verwendung von so genannten Architectural Decision Records (ADRs). Werkzeuge zur Verwaltung von ADRs gibt es bereits, aber sie arbeiten oft in einem Kontext, der für einen Softwareentwickler ungewohnt ist oder ein zusätzliches Werkzeug für die Verwendung benötigt. In dieser Arbeit wird die Möglichkeit untersucht, ADR-Werkzeuge in Form eines IDE-Plugins bereitzustellen, das Entwicklern ADR-Verwaltungsfunktionen auf bequeme Weise zugänglich macht. Das Ergebnis dieser Forschung ist die ADR Manager-Erweiterung für die Visual Studio Code IDE, die auf dem Visual Studio Code Marketplace erhältlich ist. Diese Erweiterung basiert auf dem gleichnamigen webbasierten Tool und bietet Funktionen zur Erstellung, Bearbeitung und Verwaltung von ADRs in einem lokalen Repository im Markdown-Format. Neben zwei formularbasierten ADR- Editoren mit unterschiedlichem Detaillierungsgrad bereichert die Erweiterung die Funktionalität des Markdown-Editors der IDE durch Linting-Unterstützung und schnelles Einfügen von ADR-Vorlagen in Form von Snippets. In einer empirischen Nutzerstudie mit sieben Softwareexperten erhielt die ADR-Manager-Erweiterung von den Evaluationsteilnehmern ein herausragendes Feedback hinsichtlich ihrer Benutzerfreundlichkeit im Kontext der Visual Studio Code IDE. Die Teilnehmer lobten die einfache, aber effektive Funktionalität der Erweiterung und gaben an, dass sie sich gut in die IDE-Umgebung einfügt. Auf der anderen Seite wünschten sie sich, dass die Erweiterung manchmal präziser kommunizieren würde, welche Eingaben dem Benutzer zur Verfügung stehen und wie diese eingegeben werden sollten, sodass dieser sein gewünschtes Ergebnis bekommt. Da es sich noch um einen Prototyp handelt, gibt es viele Möglichkeiten, wie die Erweiterung in Zukunft verbessert werden kann. Beispiele hierfür sind die Verbesserung der bestehenden Funktionalität, die Implementierung neuer Funktionen, um mehr Benutzer anzusprechen, oder die Implementierung für die Unterstützung weiterer ADR-Formate.