Logo
ScienceStack
Table of Contents
Fetching ...
Sign In

Interactive Diagrams for Software Documentation

Adam Štěpánek, David Kuťák, Barbora Kozlíková, Jan Byška

TL;DR

The paper addresses the challenge of maintaining and effectively navigating large codebases through documentation. It introduces an interactive, automatically generated node-link diagram as an alternative to textual API references, using glyphs to summarize code elements. The Helveg prototype analyzes C# code via static analysis (Roslyn, MSBuild, NuGet) and outputs a self-contained web application. User studies with professional developers show the approach can reveal high-level structure and code issues not easily captured by traditional API references, though usability and scalability remain concerns. The approach offers a practical path toward up-to-date, embedded, interactive documentation and can be extended to additional languages and features.

Abstract

Getting acquainted with a large codebase can be a daunting task for software developers, both new and seasoned. The description of a codebase and its development should be the purpose of its documentation. However, software documentation, if it exists at all, is usually textual and accompanied only by simple static diagrams. It is also time-consuming to maintain manually. Even an API reference, which can be generated automatically from the codebase itself, has many drawbacks. It is limited to what it can extract from the codebase, is cumbersome to navigate, and fails to capture the interwoven nature of code. We explore an alternative approach centered around a node-link diagram representing the structure of a codebase. The diagram is interactive and filterable, providing details on demand. It is designed for automation, relying on static analysis of the codebase, and thus produces results quickly and offers a viable alternative to missing or outdated documentation. To evaluate this approach, we implemented a prototype named Helveg that is able to analyze and visualize C# code. Testing with five professional programmers provided feedback on the approach's benefits and challenges, which we discuss in detail.

Interactive Diagrams for Software Documentation

TL;DR

The paper addresses the challenge of maintaining and effectively navigating large codebases through documentation. It introduces an interactive, automatically generated node-link diagram as an alternative to textual API references, using glyphs to summarize code elements. The Helveg prototype analyzes C# code via static analysis (Roslyn, MSBuild, NuGet) and outputs a self-contained web application. User studies with professional developers show the approach can reveal high-level structure and code issues not easily captured by traditional API references, though usability and scalability remain concerns. The approach offers a practical path toward up-to-date, embedded, interactive documentation and can be extended to additional languages and features.

Abstract

Getting acquainted with a large codebase can be a daunting task for software developers, both new and seasoned. The description of a codebase and its development should be the purpose of its documentation. However, software documentation, if it exists at all, is usually textual and accompanied only by simple static diagrams. It is also time-consuming to maintain manually. Even an API reference, which can be generated automatically from the codebase itself, has many drawbacks. It is limited to what it can extract from the codebase, is cumbersome to navigate, and fails to capture the interwoven nature of code. We explore an alternative approach centered around a node-link diagram representing the structure of a codebase. The diagram is interactive and filterable, providing details on demand. It is designed for automation, relying on static analysis of the codebase, and thus produces results quickly and offers a viable alternative to missing or outdated documentation. To evaluate this approach, we implemented a prototype named Helveg that is able to analyze and visualize C# code. Testing with five professional programmers provided feedback on the approach's benefits and challenges, which we discuss in detail.
Paper Structure (23 sections, 5 figures)

This paper contains 23 sections, 5 figures.

Table of Contents

  1. Introduction
  2. Background and Related Work
  3. Visualization of Code Structure
  4. Existing Tools
  5. Requirement Analysis
  6. C# Language and its Specifics
  7. Visualization Design
  8. Glyphs
  9. Entity Relationships
  10. Scalability
  11. Filtering and Highlighting
  12. Interactivity and Layout
  13. Prototype Implementation
  14. Data Mining
  15. The Diagram
  16. ...and 8 more sections

Figures (5)

  • Figure 1: A sample diagram of a namespace with several types (yellow and blue nodes). It contains several relations: declares (gray edges), type inheritance (teal edges), and method return types (purple edges). Labels were omitted.
  • Figure 2: A glyph-node representing a C# type: (A) The icon of a C# struct. (B) The innermost outline indicates that this type is non-static. (C) The middle, solid outline represents the amount of non-static members. (D) The outer, dashed outline stands for the amount of the type's static members.
  • Figure 3: Examples of glyph-nodes: (A) A solution. (B) A static with only static members. (C) A static property. (D) A non-static private class with a small amount of non-static members. (E) A method with a compiler warning. (F) A class with a compiler error.
  • Figure 4: Helveg's user interface: (A) The diagram component. (B) A type node before (smaller circle) and after expansion (larger circle) using the Toggle tool. (C) Dock allowing to switch between panels. (D) A panel containing search controls. (E) Toolbox with tools to directly modify the diagram.
  • Figure 5: Questionnaire results with color-coded Likert scores and an average result for each question.