Non Linear Software Documentation with Interactive Code Examples (2311.18057v1)

Abstract: Documentation enables sharing knowledge between the developers of a technology and its users. Creating quality documents, however, is challenging: Documents must satisfy the needs of a large audience without being overwhelming for individuals. We address this challenge with a new document format, named Casdoc. Casdoc documents are interactive resources centered around code examples for programmers. Explanations of the code elements are presented as annotations that the readers reveal based on their needs. We evaluated Casdoc in a field study with over 300 participants who used 126 documents as part of a software design course. The majority of participants adopted Casdoc instead of a baseline format during the study. We observed that interactive documents can contain more information than static documents without being distracting to readers. We also gathered insights into five aspects of Casdoc that can be applied to other formats, and propose five guidelines to improve navigability in online documents.

Interactive Software Documentation with Enhanced Code Examples

This paper introduces Casdoc, an innovative documentation format primarily designed for software developers. Casdoc structures its documents around interactive code examples, employing a non-linear navigation methodology to effectively cater to diverse user needs. This approach shifts the focus from traditional linear information presentation to a more adaptable, user-centric model. The paper evaluates Casdoc through an extensive field paper involving over 300 participants in a software design course, providing insights into the benefits and limitations of interactive documentation.

Key Features of Casdoc

Casdoc's primary innovation lies in its transformation of HTML documentation into a graph format composed of concise, interactive annotations that are deeply integrated with code examples. The transformation process utilizes annotated code files, automatically generating documents that allow users to selectively reveal annotations. This methodology aims to deliver comprehensive information without overwhelming the user, balancing depth and brevity.

The authors highlight five critical properties of Casdoc documents:

1. Focus on Code Examples: The emphasis is on providing high-quality, central code examples, supporting programmers in concrete applications of software technologies.
2. Gradual Reveal of Information: Information is progressively disclosed, allowing readers to manage content consumption and seek specifics as needed.
3. Fragmentation into Small, Self-Contained Units: By breaking information into concise fragments, Casdoc supports specific, targeted inquiries and facilitates easier navigation.
4. Explicit Structural Hints: Visual and navigational cues within the document ensure users can effectively navigate the document's structure.
5. Integration of External Content: Leveraging API documentation to enhance the information provided, thus improving coverage without additional authoring overhead.

Evaluation and Results

The field paper involved 326 participants interacting with 126 documents, revealing the effectiveness of Casdoc's non-linear, interactive approach. A significant majority—87.3%—preferred Casdoc over a traditional baseline format, indicating its suitability for dynamic learning resources. Interaction with annotations revealed that while not all users frequently accessed these interactive elements, the ability to selectively engage with content improved document navigability and relevance.

Annotations were predominantly viewed in their floating, rather than pinned, forms, suggesting that users appreciated fast and lightweight interactions. Additionally, participants interacted more with inline markers than block markers, underscoring the importance of visual design choices in the efficacy of navigational aids.

Theoretical and Practical Implications

The theoretical implications of this work lie in challenging traditional documentation structures, advocating for a more modular and interactive approach. The practical benefits are apparent in the improved efficiency in user navigation and engagement with complex documentation. Casdoc's format presents a paradigm shift that enhances informational accessibility and relevance, potentially serving as a model for future documentation systems.

Future Work

Future research may address enhancing mobile and low-interaction environments for Casdoc, exploring broader datasets beyond educational contexts, and integrating further AI-driven customization for user interactions. Improving cross-platform compatibility will be crucial to expanding Casdoc's utility.

In conclusion, Casdoc offers a compelling framework for interactive documentation, leveraging code-centric navigation, user-driven content revelation, and seamless integration of external information. Its field-tested effectiveness in an educational setting underpins its potential as a versatile tool in the evolving landscape of software documentation.