Helveg: Diagrams for Software Documentation

2025-07-14

AI Summary

Traditional API documentation relies predominantly on static textual descriptions, hindering developers’ high-level, exploratory understanding of codebases. To address this, we propose Helveg—a novel interactive documentation system that integrates software architecture visualization. Helveg automatically parses C# source code to generate a structured, node-link graph representing architectural elements; it employs semantically rich node glyphs, multi-granularity filtering, and natural interaction paradigms—enabling on-demand switching between overviews and details and supporting customizable exploration paths. Built upon a web-based visualization framework, it delivers dynamic rendering and a responsive UI. A controlled user study demonstrates that Helveg significantly outperforms baseline tools in readability, intuitiveness, and overall user experience, thereby improving codebase comprehension efficiency.

Technology Category

• Cognitive Modeling & Cognitive Systems: Agent Architectures
• Natural Language Processing: Code Generation / Program Synthesis from Natural Language
• Data Mining & Knowledge Management: Data Visualization & Summarization

Application Category

• Web Mining and Content Analysis: Web data visualization
• Graph Algorithms and Modeling for the Web: Foundation models and LLMs for Web-related graphs
• Semantics and Knowledge: Data modeling to support human-machine intelligence, including LLMs agents, intelligent system behavior, explanations, and user-friendly interactions

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.

Problem

• Improving codebase understanding via interactive diagrams
• Enhancing readability and intuitiveness of software documentation
• Redesigning glyphs and UI for better user experience

Innovation

• Interactive node-link diagrams for API documentation
• Expressive glyphs and flexible filtering capabilities
• Automated C# codebase visualization tool