Reusable software documentation with phrase annotations

Abstract

Problem: Reoccurring software documentation fragments called documentation phrases crosscut documentation body and introduce undesired redundancy. The redundancy imposes problems with software documentation development and evolution. Objective: We want to reduce the negative effect caused by documentation phrases redundancy by centralizing the documentation phrases sources. This way a documentation phrase will have a single source that can be used for maintenance and evolution. Method: We discuss the nature of documentation phrases and argue for the support of their parametrization. We present a new documentation phrase instantiation method based on source code annotations. The provides free IDE support for writing documentation and is aided by our tool prototype. Results and contributions: Our contributions of this paper include identification of documentation phrase parametrization and the annotation-based documentation phrase instantiation. The annotation-based documentation phrase instantiation method enables to reduce the effort needed for documentation development and evolution.

Preliminary Report on Empirical Study of Repeated Fragments in Internal Documentation

“…Their tool CommentWeaver is able to weave documentation phrases the same way as advices are woven in aspect-oriented programming. Our work presented in [6] continues in their work. There we propose using source code annotations to indicate program elements that should be documented by a given documentation phrase.…”

“…In conclusion, the presented results underline the significance of approaches like the one we presented in [6], or the one by Horie et al [7], which centralize the management of such a documentation phrase into one place and thus ease their maintenance and evolution.…”

“…In this report we present preliminary results that indicate that there is a significant duplication of text in internal documentation. These repeating documentation fragments constitute documentation phrases discussed in several works -e.g., our previous work [6], or the one by Horie et al [7]. This way the study has a potential to highlight the importance of those works and it may stimulate further attention to this topic.…”

“…Second, the modified PMD CPD detected solely static phrases -fragments of the documentation that were copy/-pasted in documentation. Inclusion of parametrized documentation phrases [6] would be welcome.…”

“…Documentation fragments that represent the same documentation phrase usually document the same domain or design property that is shared by the documented program elements [6]. Horie et al [7] likened the documentation phrases to crosscutting concerns from aspect oriented programming (AOP [8]).…”