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

…ion-module-dbodor

Documentation module

modules/documentation/ex_suitability.md

@@ -1,39 +1,33 @@
 ---
-title: What is suitable documentation?
+title: Suitable documentation
 type: exercise
 order: 4
 ---
 
-# What is suitable documentation?
+# What is suitable documentation for "your" project?
 
-## Step 1: Choose a software project
+As a group, consider the project that you worked on for your homework assignment.
 
-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:
+## Type(s) of documentation
 
-- [ESMValTool](https://research-software-directory.org/software/esmvaltool)
-- [LitStudy](https://research-software-directory.org/software/litstudy)
-- [Haddock](https://research-software-directory.org/software/haddock3)
-- [worcs](https://cjvanlissa.github.io/worcs/index.html)
-- [democracy-topic-modelling](https://research-software-directory.org/software/democracy-topic-modelling)
+*Which type of of documentation currently exists? Is there anything missing/do you think anything is a bit over the top?*
 
-## 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?*
+It is not necessary to dive too deep into the codebase/repository for this. Answer based on what you can see 
 
+- README
+- Tutorial(s)
+- In-code documentation
+- API reference
+- Overview of components
 - User documentation
 - Developer documentation
 - Deployment documentation
 
-*Which content would you include?*
-The following (non-exhaustive) list of documentation items:
+
+## Documentation contents
+
+*Which of the following piees of information are/should be included, and where?*
 
 - Purpose
 - Authors
@@ -47,3 +41,7 @@ The following (non-exhaustive) list of documentation items:
 - How you want to be asked questions (mailing list or forum or chat or issue tracker)
 - Possibly a FAQ section
 - Contribution guide
+
+## Motivation
+
+*How would you motivate your colleagues/researchers to contribute to the documentation?*

modules/documentation/exercise-which-documentation.md → modules/documentation/exercise-levels.md

@@ -1,7 +1,7 @@
 ---
-title: When to use which documentation?
+title: Levels of documentation
 type: exercise
-order: 4
+order: 3
 ---
 
 # When to use which documentation?
@@ -13,9 +13,9 @@ 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
+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:
@@ -32,4 +32,3 @@ and finds it important that when she moves on to a different job that the softwa
 ## 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/reading.md

@@ -6,12 +6,15 @@ order: 5
 
 ## Reusability requires good documentation
 
-<https://book.the-turing-way.org/reproducible-research/code-reuse/code-reuse-overview>
+- https://book.the-turing-way.org/reproducible-research/code-reuse/code-reuse-overview
 
 ## README
+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.
 
-<https://makeareadme.com>
+- https://makeareadme.com>
+- https://gist.github.com/jxson/1784669
 
 ## Popular tools foor building more complex documentation
 
-<https://coderefinery.github.io/documentation/tools>
+- https://coderefinery.github.io/documentation/tools

modules/documentation/slides_documentation.md

@@ -16,7 +16,7 @@ author: Luisa Orozco, Barbara Vreede, Jaro Camphuijsen, Carlos Martinez, Max Pau
 ## What is documentation?
 
 - Provides context for your work
-- Allows your collaborators and future you to understand what has been done and why
+- Allows your collaborators **and future you** to understand what has been done and why
 
 ===
 
@@ -25,26 +25,27 @@ author: Luisa Orozco, Barbara Vreede, Jaro Camphuijsen, Carlos Martinez, Max Pau
 ## 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
+- A contributor should be able to add to, improve, or fix code
 
 ===
 
 <!-- .slide: data-state="standard" -->
 
-## Documentation types
+## Documentation purpose types
+
+Documentation can have different purposes:
 
-User documentation
-- Purpose: What does the software do?
-- How can it be used: provide examples
+- **User documentation**: What does the software do? How can it be used?
+<!-- .element: class="fragment" data-fragment-index="1" -->
 
-Developer documentation
-- How can your software be modified or extended?
+- **Developer documentation**: How can your software be modified or extended?
+<!-- .element: class="fragment" data-fragment-index="2" -->
 
-Deployment documentation
-- Hardware and software requirements
+- **Deployment documentation**: What hardware and software requirements are there?
+<!-- .element: class="fragment" data-fragment-index="3" -->
 
 ===
 
@@ -98,7 +99,7 @@ Note:
 In-code documentation:
 
 + Makes code more understandable
-+ Explains decisions we made
++ Explains decisions that were made
 
 ===
 
@@ -196,24 +197,26 @@ They follow a standardized syntax.
 
 ## Tools
 
-+ **Sphinx** (documentation generator)
++ **Sphinx** / **mkdocs** (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
+  - automatically deploys documentation generated above
 
 ===
 
 <!-- .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.
+Documentation is a vital part of a project, and should be kept and created alongside the corresponding code.
+
+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

modules/documentation/types-of-documentation.md

@@ -1,7 +1,7 @@
 ---
 title: Types of documentation
 type: reading
-order: 3
+order: 2
 ---
 
 # Types of documentation and when to use them