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

Embedded software
Architectural design
Application programming interfaces (API)
Software engineering

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

Documentation as a cross-cutting concern of sofware. / Palmer, James D.; McAddis, Nakai.

SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication. Association for Computing Machinery, Inc, 2019. 18 (SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication).

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

Palmer, JD & 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, 37th ACM International Conference on the Design of Communication, SIGDOC 2019, Portland, United States, 10/4/19. https://doi.org/10.1145/3328020.3353949
Palmer JD, McAddis N. Documentation as a cross-cutting concern of sofware. In SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication. Association for Computing Machinery, Inc. 2019. 18. (SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication). https://doi.org/10.1145/3328020.3353949
Palmer, James D. ; McAddis, Nakai. / Documentation as a cross-cutting concern of sofware. SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication. Association for Computing Machinery, Inc, 2019. (SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication).
@inproceedings{1c06ed4e6497451e96529470fb290546,
title = "Documentation as a cross-cutting concern of sofware",
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.",
keywords = "Collaborative document generation, Comments, Documentation generation, Software documentation, View-oriented documentation",
author = "Palmer, {James D.} and Nakai McAddis",
year = "2019",
month = "10",
day = "4",
doi = "10.1145/3328020.3353949",
language = "English (US)",
series = "SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication",
publisher = "Association for Computing Machinery, Inc",
booktitle = "SIGDOC 2019 - Proceedings of the 37th ACM International Conference on the Design of Communication",

}

TY - GEN

T1 - Documentation as a cross-cutting concern of sofware

AU - Palmer, James D.

AU - McAddis, Nakai

PY - 2019/10/4

Y1 - 2019/10/4

N2 - 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.

AB - 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.

KW - Collaborative document generation

KW - Comments

KW - Documentation generation

KW - Software documentation

KW - View-oriented documentation

UR - http://www.scopus.com/inward/record.url?scp=85074797725&partnerID=8YFLogxK

UR - http://www.scopus.com/inward/citedby.url?scp=85074797725&partnerID=8YFLogxK

U2 - 10.1145/3328020.3353949

DO - 10.1145/3328020.3353949

M3 - Conference contribution

AN - SCOPUS:85074797725

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

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

PB - Association for Computing Machinery, Inc

ER -