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.