Document all the things! (How again?)

Kurzfassung

Documentation is key in sustaining (research) software. How can we expect future users, developers and maintainers to run, use, contribute to or maintain software if they cannot refer to its documentation? While this point seems - almost tautologically - clear, the question of how to best document a software project remains unanswered, although there are ongoing efforts, including dedicated conferences such as "Write The Docs", that aim to provide answers. In this mini-workshop we will have a brief look at a specific aspect of documentation: documentation types. Based on a use case from a new research project working to sustain a research software, we will discuss requirements of documentation for research software in terms of: (1) What must or should be documented? What types of documentation should a research software project provide in order to survive and be re-usable? Is there a minimal set and a maximal set of required documentation types or levels? (2) How do the different types of required documentation determine how the documentation should actually be written (or generated)? (3) What are the requirements for tooling that supports the creation of the required documentation? Is such tooling available? In the course of the workshop we will try to find some answers to these questions, with the aim to generate the starting point for a document on the documentation of research software. We can then collaborate further on this document during the hack session to create an output (a blog post/whitepaper/publication) that will help other research software practitioners to configure documentation of their own projects respectively.