Presentation Open Access

Continuous Documentation for Users, Developers and Maintainers

Frust, Tobias

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.

Files (4.3 MB)
Name Size
software-documentation.pdf
md5:a40c35327604276ec81459711db0702f
2.0 MB Download
software-documentation.pptx
md5:69f81c5de97e87005d01b77532b7ea5d
2.3 MB Download
81
46
views
downloads
All versions This version
Views 8181
Downloads 4646
Data volume 92.2 MB92.2 MB
Unique views 6969
Unique downloads 3434

Share

Cite as