No Title

When to use which documentation?

Joanne is working on her research software 'WeatherMap' that analyses and summarizes measurements from weather stations.

Here is a list of possible forms of documentation:

  1. A basic README file containing: quick installation instructions, two lines explaining why the software was created, two basic examples of how you can use the software.
  2. A tutorial: 'Finding unusual patterns in daily average temperatures using WeatherMap'.
  3. In-code documentation: Comments in her code that explain why she made certain implementation choices.
  4. API reference: Detailed description of each function/class of WeatherMap.
  5. Overview of components: A detailed overview of each component in the software.
  6. User documentation: Extensive documentation on how users can use each of the functionalities of WeatherMap.
  7. Naming: Logical names for functions, modules, and classes so that it is immediately clear what the corresponding piece of code does.

For the following scenarios, which forms of documentation would you suggest Joanne to incorporate in her project:

Scenario A:

Joanne just started her PhD and is the only one using WeatherMap to create results for her first paper. She does not really care about anyone else using her software.

Scenario B:

Joanne works together with a few other PhD students in her research group on the software. She wants to make it easier for other researchers in her group to also adopt the software, and finds it important that when she moves on to a different job that the software can be still be used and improved in her absence.

Scenario C:

Joanne and her colleagues spend half of their time updating and improving WeatherMap. They have a large community of users around the globe that depend on WeatherMap for their research.