Helveg: Diagrams for Software Documentation

TL;DR

Helveg introduces an interactive diagram-based approach for software documentation visualization, enhancing understanding of codebases through high-level overviews and detailed views, specifically tested on C# projects.

Contribution

The paper presents an improved version of Helveg, a tool that visualizes C# codebases with interactive diagrams, addressing previous usability issues and enhancing readability and user experience.

Findings

User testing confirmed improved readability and usability.

Major glyph and interface redesigns enhanced intuitiveness.

Helveg effectively visualizes code structure for developers.

Abstract

Software developers often have to gain an understanding of a codebase. Be it programmers getting onboarded onto a team project or, for example, developers striving to grasp an external open-source library. In either case, they frequently turn to the project's documentation. However, documentation in its traditional textual form is ill-suited for this kind of high-level exploratory analysis, since it is immutable from the readers' perspective and thus forces them to follow a predefined path. We have designed an approach bringing aspects of software architecture visualization to API reference documentation. It utilizes a highly interactive node-link diagram with expressive node glyphs and flexible filtering capabilities, providing a high-level overview of the codebase as well as details on demand. To test our design, we have implemented a prototype named Helveg, capable of automatically generating diagrams of C\# codebases. User testing of Helveg confirmed its potential, but it also revealed problems with the readability, intuitiveness, and user experience of our tool. Therefore, in this paper, which is an extended version of our VISSOFT paper with DOI 10.1109/VISSOFT64034.2024.00012, we address many of these problems through major changes to the glyph design, means of interaction, and user interface of the tool. To assess the improvements, this new version of Helveg was evaluated again with the same group of participants as the previous version.