View article

Novel presentation approaches are needed to improve the way information seekers, such as programmers, use documentation. Documentation is a crucial asset to understand an unfamiliar software system [23, 58]. Yet, creating good documents requires a lot of e ort and expertise. Software engineering researchers have proposed di erent techniques to generate content (eg,[11, 39, 50]) or retrieve it from knowledge bases (eg,[17, 55, 75]), which can alleviate some of this e ort. However, documentation quality is multi-faceted [32]: it must not only contain enough information to address the concrete needs of its audience [15], but the information must also be readable, navigable, and understandable [2, 74]. These aspects, which relate to how the information is organized and presented, have not been studied as extensively. As a result, current documentation formats may fail to emphasize the most useful fragments when too much content is available [77].

Casdoc is a solution to improve the navigability of content in code-oriented documents. In a Casdoc document, readers interact with code elements to reveal further explanations of those elements (see Figure 1 in Section 2). Information about elements that are irrelevant to a reader remains hidden to avoid unnecessary distractions. Casdoc relies on popovers and dialogs to achieve this objective. Hence, it recasts two graphical elements which are typically used for secondary navigation aid as the primary structure to organize the content of a document. As a result, this strategy splits the content of a document into concise annotations. Annotations are created by the document’s author, who inserts them …