Continuous System and User Documentation Integration
• Conference Paper
Publisher
Institute of Electronic Engineers (IEEE)
Subjects
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 organization 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.