Merge pull request #104 from esciencecenter-digital-skills/documentat…

…ion-module

Add Documentation module

modules/documentation/ex_readme.md

@@ -0,0 +1,15 @@
+---
+title: Include a README file
+type: exercise
+order: 4
+---
+
+
+# Include a README file
+
+The README file is usually the first thing users/collaborators see when visiting your GitHub repository.
+Use it to communicate important information about your project! For many smaller or mid-size projects, this is enough documentation.
+It’s not that hard to make a basic one, and it’s easy to expand as needed.
+
+- https://www.makeareadme.com/
+- https://gist.github.com/jxson/1784669

modules/documentation/ex_suitability.md

@@ -0,0 +1,47 @@
+---
+title: What is suitable documentation?
+type: exercise
+order: 4
+---
+
+# What is suitable documentation?
+
+## Step 1: Choose a software project
+
+Choose a software project for this exercise, preferably one you are familiar with.
+
+If you don't have a project in mind, you can use one of the following:
+- [Democracy Topic Modelling](https://research-software-directory.org/software/democracy-topic-modelling)
+- [ESMValTool](https://research-software-directory.org/software/esmvaltool)
+- [Haddock](https://research-software-directory.org/software/haddock3)
+- [worcs](https://cjvanlissa.github.io/worcs/index.html)
+
+## Step 2: Discuss type(s) of documentation
+
+*Look at the software repository or page in the Research Software Directory*
+
+- Is documentation for this project important? Why?
+- How would you describe a useful documentation for this project?
+- How can you motivate your colleagues to contribute to the documentation?
+
+*What type of documentation seems appropriate to you?*
+
+- User documentation
+- Developer documentation
+- Deployment documentation
+
+*Which content would you include?*
+The following (non-exhaustive) list of documentation items:
+
+- Purpose
+- Authors
+- License
+- Recommended citation
+- Copy-paste-able example to get started
+- Dependencies and their versions or version ranges
+- Installation instructions
+- Tutorials covering key functionality
+- Reference documentation (e.g. API) covering all functionality
+- How you want to be asked questions (mailing list or forum or chat or issue tracker)
+- Possibly a FAQ section
+- Contribution guide

modules/documentation/exercise-which-documentation.md

@@ -0,0 +1,35 @@
+---
+title: When to use which documentation?
+type: exercise
+order: 4
+---
+
+# 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.
+5. API reference: Detailed description of each function/class of WeatherMap.
+6. Overview of components: A detailed overview of each component in the software
+7. User documentation: Extensive documentation on how users can use each of the functionalities of WeatherMap
+8. 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.
+

modules/documentation/index.md

@@ -0,0 +1,9 @@
+---
+title: Documentation
+category: Development
+order: 13
+abstract: Why should researchers document their code?
+author: eScience Center
+thumbnail: "thumbnail-documentation.jpg"
+visibility: visible
+---

modules/documentation/info.md

@@ -0,0 +1,10 @@
+---
+title: Learning objectives
+type: info
+order: 0
+---
+
+Obtain the skills and knowledge necessary to address the following questions:
+- What is code documentation?
+- Why is documentation considered best practice in software development and how do I communicate that to researchers?
+- What are some of the ways code is documented in practice?

modules/documentation/reading.md

@@ -0,0 +1,17 @@
+---
+title: Further reading
+type: reading
+order: 5
+---
+
+## Reusability requires good documentation
+
+<https://book.the-turing-way.org/reproducible-research/code-reuse/code-reuse-overview>
+
+## README
+
+<https://makeareadme.com>
+
+## Popular tools foor building more complex documentation
+
+<https://coderefinery.github.io/documentation/tools>

modules/documentation/slides_documentation.md

@@ -0,0 +1,219 @@
+---
+title: Documentation
+type: slides
+order: 1
+author: Luisa Orozco, Barbara Vreede, Jaro Camphuijsen, Carlos Martinez, Max Paulus, Robin Richardson
+---
+
+<!-- .slide: data-state="title" -->
+
+# Documentation
+
+===
+
+<!-- .slide: data-state="standard" -->
+
+## What is documentation?
+
+- Provides context for your work
+- Allows your collaborators and future you to understand what has been done and why
+
+===
+
+<!-- .slide: data-state="standard" -->
+
+## Why document software?
+
+Make your software reusable:
+
+- A user should be able to run your software in the same way as you do now 
+- A user should be able to install your software
+- A contributor should be able to add or improve code
+
+===
+
+<!-- .slide: data-state="standard" -->
+
+## Documentation types
+
+User documentation
+- Purpose: What does the software do?
+- How can it be used: provide examples
+
+Developer documentation
+- How can your software be modified or extended?
+
+Deployment documentation
+- Hardware and software requirements
+
+===
+
+<!-- .slide: data-state="standard" -->
+
+## Documentation formats
+
+<!-- add visual with documentation format with increasing complexity -->
+
+- In-code: intended for contributors (comments, docstrings, ...)
+- README: simple text file, first thing that users/collaborators see
+- Websites, Wikis 
+
+===
+
+<!-- .slide: data-state="standard"  -->
+
+## A good README file
+
++ README file is first thing a user/collaborator sees
++ What should be included in README files?
+<ul>
+  <li contenteditable="true">...</li>
+  <li contenteditable="true">...</li>
+  <li contenteditable="true">...</li>
+  <li contenteditable="true">...</li>
+  <li contenteditable="true">...</li>
+  <li contenteditable="true">...</li>
+  <li contenteditable="true">...</li>
+</ul>
+
+
+Note:
++ A descriptive project title
++ Motivation (why the project exists) and basics
++ Installation / How to setup
++ Copy-pasteable quick start code example
++ Usage reference (if not elsewhere)
++ Recommended citation if someone uses it
++ Other related tools ("see also")
++ Contact information for the developer(s)
++ License information
++ Contributing guidelines
+
+===
+
+<!-- .slide: data-state="standard"  -->
+
+## Why write in-code documentation?
+
+In-code documentation:
+
++ Makes code more understandable
++ Explains decisions we made
+
+===
+
+<!-- .slide: data-state="standard"  -->
+
+## When **not** to use in-code documentation?
+
++ When the code is self-explanatory
++ To replace good variable/function names
++ To replace version control
++ To keep old (zombie) code around
+
+===
+
+<!-- .slide: data-state="standard"  -->
+
+## Readable code vs commented code
+
+```python=
+# convert from degrees celsius to fahrenheit
+def convert(d):
+    return d * 5 / 9 + 32
+```
+vs
+```python=
+def celsius_to_fahrenheit(degrees):
+    return degrees * 5 / 9 + 32
+```
+
+===
+
+<!-- .slide: data-state="standard"  -->
+
+## What makes a good comment?
+
+**Comment A**
+
+<pre data-id="code-animation"><code style="overflow: hidden;" data-trim class="python">
+# Now we check if temperature is larger than -50:
+if temperature > -50:
+    print('do something')
+</code></pre>
+
+**Comment B**
+
+<pre data-id="code-animation"><code style="overflow: hidden;" data-trim class="python">
+# We regard temperatures below -50 degrees as measurement errors
+if temperature > -50:
+    print('do something')
+</code></pre>
+
+How are these different? Which one do you prefer?
+
+===
+
+<!-- .slide: data-state="standard"  -->
+
+## Docstrings: a special kind of comment
+
+```python=
+def celsius_to_fahrenheit(degrees):
+  """Convert degrees Celsius to degrees Fahrenheit."""
+  return degrees * 5 / 9 + 32
+```
+
+Why is this OK?
+
+Note:
+Docstrings can be used to generate user documentation.
+They are accessible outside the code.
+They follow a standardized syntax.
+
+===
+
+<!-- .slide: data-state="standard"  -->
+
+## In-code commenting: key points
+
++ Explicit, descriptive naming already provides important documentation.
++ Comments should describe the why for your code, not the what.
++ Writing docstrings is an easy way to write documentation while you code, as they are accessible outside the code itself.
+
+===
+
+<!-- .slide: data-state="standard"  -->
+
+## User/API documentation
+
++ What if a README file is not enough?
++ How do I easily create user documentation?
+
+===
+
+<!-- .slide: data-state="standard"  -->
+
+## Tools
+
++ **Sphinx** (documentation generator)
+  - creates nicely-formatted HTML pages out of .md or .rst files
+  - programming language independent
++ **Github pages** (deploy your documentation)
+  - set up inside your GitHub repository
+  - automatically deploys your Sphinx-generated documentation
+
+===
+
+<!-- .slide: data-state="standard" -->
+
+## Take-home message
+
++ Depending on the purpose and state of the project documentation needs to meet different criteria.
++ Documentation can take different shapes:
+  + Readable code
+  + In-code comments
+  + Docstrings
+  + README files
+  + Tutorials/notebooks
++ Documentation is a vital part of a project, and should be kept and created alongside the corresponding code.

modules/documentation/types-of-documentation.md

@@ -0,0 +1,33 @@
+---
+title: Types of documentation
+type: reading
+order: 3
+---
+
+# Types of documentation and when to use them
+
+## Why document projects?
+
+- Quickly get users started
+- Show how to use the software
+- Explain concepts behind the software
+- Describe internal machinery of a project
+
+## Types of documentation
+
+Documentation serves different goals, therefore there are different types: 
+- **Tutorials**: learning-oriented, allows the newcomer to get started
+- **How-to guides**: goal-oriented, shows how to solve a specific problem
+- **Explanation**: understanding-oriented, explains a concept
+- **Reference**: information-oriented, describes the machinery
+
+## README file: (how-to guide)
+- First thing a user/collaborator sees
+- Contains basic setup instructions and information about the project
+
+## In-code documentation (reference)
+- Technical documentation in the code
+- For example ```# comments```
+
+## API reference (reference)
+- API reference: detailed description of how each function/class in the code can be used