Documentation as a cross-cutting concern of sofware

James D. Palmer, Nakai McAddis

Research output: Chapter in Book/Report/Conference proceedingConference contribution

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 workfows, 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 diferent 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.

Original languageEnglish (US)
Title of host publicationSIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication
PublisherAssociation for Computing Machinery, Inc
ISBN (Electronic)9781450367905
DOIs
StatePublished - Oct 4 2019
Event37th ACM International Conference on the Design of Communication, SIGDOC 2019 - Portland, United States
Duration: Oct 4 2019Oct 6 2019

Publication series

NameSIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication

Conference

Conference37th ACM International Conference on the Design of Communication, SIGDOC 2019
CountryUnited States
CityPortland
Period10/4/1910/6/19

    Fingerprint

Keywords

  • Collaborative document generation
  • Comments
  • Documentation generation
  • Software documentation
  • View-oriented documentation

ASJC Scopus subject areas

  • Computer Networks and Communications
  • Computer Graphics and Computer-Aided Design

Cite this

Palmer, J. D., & McAddis, N. (2019). Documentation as a cross-cutting concern of sofware. In SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication [18] (SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication). Association for Computing Machinery, Inc. https://doi.org/10.1145/3328020.3353949