Lessons learned from the adoption of documentation generators in scientific software development

• Michael Moser
• Josef Pichler

In scientific software development the production of technical software documentation is often neglected and usage of documentation tools which assist in the process of documentation generation is limited. Nonetheless, there is a widespread agreement in the scientific computing community that documentation positively influences software quality and thereby helps to mitigate the risk of project failure. We accompanied the introduction of documentation generators within an industrial scientific computing project over a period of one year in order to improve understandability and overall software quality. The used tools ranged from standard API documentation tools to proprietary research prototypes. However, although technically mature and adequate for the intended documentation tasks none of the documentation generators was finally used and the required documentation was created manually. In this paper we report on lessons learned and discuss reasons that lead to the rejection of the proposed documentation generators.