Continuous System and User Documentation Integration
October 2014 • Conference Paper
Todd Waits, Joseph D. Yankel
This paper describes a process that produces PDF, HTML, and Word-based documentation from multiple authors and integrates it with an existing automated build system.
Abstract
Formal user and system documentation is often completely ignored by development teams. This is a direct result of the pain standard documentation tools and processes cause to technical teams. Traditional documentation models hamper the velocity of development. User and/or system documentation is often created and maintained using clunky binary files (i.e., docx files).
Generally, collaboration systems include passing updated versions through long email chains, or network file shares. Additionally, proprietary formats tend to suffer from inconsistencies across operating systems, which can lead to data corruption across teams with disparate work environments.
Storing binary files in version control systems is a solution to some of these problems, but versioning binary files is still challenging. Automating and integrating such files into a software development lifecycle is problematic at best, and often results in documents languishing behind the pace of a project, or being deprecated entirely.
This paper, given at the Professional Communication Conference (IPCC) in 2014, describes a new process our organiation developed to rapidly produce PDFs, HTML, and Word-based documentation from multiple authors and integrate it with our existing automated build system.
The process is tool/environment independent and takes full advantage of a version control system. This approach has increased our efficiency, communication and collaboration in an often-overlooked area in the software development process.