Migrating Software Design Documentation from Microsoft Word to AsciiDoc: A Case Study

Software design documentation is an important artifact for software developers to implement their products. However, keeping documentation up-to-date is challenging; software developers have to spend time frequently modifying, reviewing, and merging documentation changes written in Microsoft Word. To address the up-to-dateness issue, a software team in a company has introduced AsciiDoc, which is a lightweight markup language, for design documentation so that they can review and merge changes using the same tools as source code. This study investigates the impact of the introduction of AsciiDoc by conducting a developer survey and a repository mining. The survey results show that developers perceived that AsciiDoc enabled them to update their documents efficiently. The result of the repository mining suggests that their software development velocity has improved. Based on the observations, we believe that the introduction of AsciiDoc has improved the efficiency of documentation workflows.