Continuous Documentation for Users, Developers and Maintainers

This talk covers the often neglected and “hated” aspect of software documentation that is indispensable in a sustainable research software development process. A good, up-to-date and easily accessible software documentation lays the foundation for broader usage and collaboration. Software documentation usually covers three different components: user documentation, instructions how to modify and contribute to the software and a low-level API documentation. When starting developing a new research software, the documentation should be considered from the very beginning. Maintaining an up-to-date software documentation with good coverage in an exascale ready scientific software stack is only achievable, if the contribution process clearly includes a check for documentation adding or updates. This check can only be automated partially and usually requires a manual review process. All contributions must be made with the understanding, that documentation is a key aspect of any contribution. Things get never cleaned up later. Recurrent tasks should be automated wherever possible to reduce the impact of manual errors, e.g. the deployment of software documentation. This talk provides a set of best practices for software documentation in science combined with concrete examples from real-world scientific software solutions.