Documentation as a cross-cutting concern of software

Abstract

Traditionally, software documentation is either embedded directly into the source code as comments and therefore tightly coupled to it or maintained separately and completely divorced from the code. This work explores an alternative mechanism for writing, storing, and maintaining software documentation where comment points derived from revision control artifacts associated with the software are embedded in source code. These comment points abstractly link to software documentation, which is stored separately from the source code but remains maintainable from the source code using traditional software development tools and workflows, or using documentation focused tools like wikis. By treating documentation as a cross-cutting concern of source code, we intend to increase the modularity of documentation. This, in turn, allows different documentation concerns to be supported without mixing those concerns. Examples of such concerns include documentation associated with the architectural design, articulated requirements for the software, a literate description of algorithms, external developer API documentation, accessibility of international documentation, and pedagogical exposition.