cosmetics

content/collaboration/code-review.md

@@ -7,7 +7,7 @@ ask for changes in a pull request, how to suggest a change in a pull request,
 and how to modify a pull request.
 
 This will enable research groups to work more collaboratively and to not only
-improve the code quality but also to learn from each other.
+improve the code quality but also to **learn from each other**.
 
 
 ## Exercise
@@ -122,7 +122,7 @@ and later open a new one. It can even be counter-productive to do so: This can
 fragment the discussion and the history of the pull request and can make it
 harder to understand the context of the changes.
 
-A much better mechanism to recognize that pull requests are not implemented
+A much better mechanism is to recognize that pull requests are not implemented
 from a specific commit to a specific branch, but **always from a branch to a
 branch**.
 
@@ -131,7 +131,7 @@ commits to the same source branch. This way the pull request will be updated
 automatically and the reviewer can see the new changes and comment on them.
 
 The fact that pull requests are from branch to branch also strongly suggests
-that it is a good practice to create a new branch for each pull request.
+that it is a good practice to **create a new branch for each pull request**.
 Otherwise you could accidentally modify an open pull request by adding new
 commits to the source branch.
 
@@ -140,5 +140,5 @@ commits to the source branch.
 
 - Our process isn't just about code now.  It's about discussion and
   working together to make the whole process better.
-- GitHub discussions and reviewing are quite powerful and can make
+- GitHub (or GitLab) discussions and reviewing are quite powerful and can make
   small changes easy.

content/collaboration/demo-discussion.md

@@ -1,5 +1,5 @@
 (collaboration-demo-discussion)=
 
-# Conclict resolution, rebasing, and organizational strategies
+# Conflict resolution, rebasing, and organizational strategies
 
 (40 min demo and discussion)

content/collaboration/forking-workflow.md

@@ -15,7 +15,7 @@ accept modifications without having to grant write access to others.
 
 :::{prereq} Exercise preparation
 - The exercise repository is now different:
-  <https://github.com/workshop-material/recipe-book-forking-exercise> (note the `-forking-exercise`).
+  <https://github.com/workshop-material/recipe-book-forking-exercise> (note the **-forking-exercise**).
 - First **fork** the exercise repository to your GitHub account.
 - Then **clone your fork** to your computer (if you wish to work locally).
 - Double-check that you have forked the correct repository.

content/collaboration/same-repository.md

@@ -135,7 +135,7 @@ Here are all the keywords that GitHub recognizes:
 Then observe what happens in the issue once your commit gets merged: it will
 automatically close the issue and create a link between the issue and the
 commit. This is very useful for tracking what changes were made in response to
-which issue and to know from when until when precisely the issue was open.
+which issue and to know from when **until when precisely** the issue was open.
 
 
 ### (4) Push to GitHub as a new branch
@@ -275,6 +275,6 @@ To protect a branch in your own repository, go to "Settings" -> "Branches".
 ### Summary
 
 - We used all the same pieces that we've learned previously.
-- But we successfully contributed to a collaborative project!
+- But we successfully contributed to a **collaborative project**!
 - The pull request allowed us to contribute without changing directly:
   this is very good when it's not mainly our project.

content/documentation.md

@@ -104,6 +104,14 @@ See also the
 [JOSS review checklist](https://joss.readthedocs.io/en/latest/review_checklist.html).
 
 
+## Diátaxis
+
+Diátaxis is a systematic approach to technical documentation authoring.
+
+- Overview: <https://diataxis.fr/>
+- How to use Diátaxis **as a guide** to work: <https://diataxis.fr/how-to-use-diataxis/>
+
+
 ## What if you need more than a README?
 
 - Write documentation in
@@ -127,14 +135,6 @@ See also the
   [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/)
 
 
-## Diátaxis
-
-Diátaxis is a systematic approach to technical documentation authoring.
-
-- Overview: <https://diataxis.fr/>
-- How to use Diátaxis **as a guide** to work: <https://diataxis.fr/how-to-use-diataxis/>
-
-
 ## Exercise: Set up a Sphinx documentation
 
 :::{prereq} Preparation
@@ -158,13 +158,13 @@ Which repository to use? You have 3 options:
 
 There are at least two ways to get started with Sphinx:
 1. Use `sphinx-quickstart` to create a new Sphinx project.
-1. **This is what we will do**: Create three files (`doc/conf.py`, `doc/index.md`, and `doc/about.md`)
+1. **This is what we will do instead**: Create three files (`doc/conf.py`, `doc/index.md`, and `doc/about.md`)
    as starting point and improve from there.
 
 ::::{exercise} Exercise: Set up a Sphinx documentation
 1. Create the following three files in your project:
    ```
-   planets/
+   planets/      <- or your own project
    ├── doc/
    │   ├── conf.py
    │   ├── index.md
@@ -192,7 +192,7 @@ There are at least two ways to get started with Sphinx:
    html_theme = "sphinx_rtd_theme"
    ```
 
-   This is `index.md` (feel free to adjust):
+   This is `index.md` (feel free to change the example text):
    ```markdown
    # Our code documentation
 
@@ -242,11 +242,16 @@ There is a lot more you can do:
   ```
 - [sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/)
   provides a local web server that will automatically refresh your view
-  every time you save a file - which makes writing and testing much easier.
+  every time you save a file - which makes writing with live-preview much easier.
 
 
 ## Demo: Building documentation with GitHub Actions
 
+:::{instructor-note}
+- Instructor presents.
+- Learners are encouraged to try this later on their own.
+:::
+
 First we need to extend the `environment.yml` file to include the necessary packages:
 ```{code-block} yaml
 ---
@@ -319,10 +324,11 @@ Now:
 - Go to "Settings" -> "Pages" -> "Branch" -> `gh-pages` -> "Save".
 - Look at "Actions" tab and observe the workflow running and hopefully
   deploying the website.
-- Finally visit the generated site. You find it by clicking the About wheel
+- Finally visit the generated site. You can find it by clicking the About wheel
   icon on top right of your repository. There, select "Use your GitHub Pages
   website".
-- **This is how we build almost all of our lesson websites** (including this one).
+- **This is how we build almost all of our lesson websites**,
+  including this one!
 - Another popular place to deploy Sphinx documentation is [ReadTheDocs](https://readthedocs.org/).
 
 

content/index.md

@@ -8,10 +8,9 @@ workshop we assume that most workshop participants use Python in their work or
 a leading a group which uses Python.  Therefore, some of the examples will use
 Python as the example language.
 
-We will work with an example project and go through all the steps of a typical
-software project.  Once we have seen the building blocks, we will try to apply
-them to own projects. Workshop participants will receive and also learn to give
-constructive code feedback.
+We will work with an example project and go through all important steps of a typical
+software project.  Once we have seen the building blocks, we will try to **apply
+them to own projects**.
 
 
 ## Prerequisites
@@ -39,7 +38,6 @@ constructive code feedback.
 - 13:00-13:30 - **Welcome and introduction**
   - Practical information (tools, communication, breaks, etc.)
   - Motivation (reproducibility, robustness, distribution, improvement, trust, etc.)
-  - What will learn and achieve from this course?
   - {ref}`example-project`
 
 - 13:30-14:45 - {ref}`version-control` (1/2)

content/version-control/branching-and-committing.md

@@ -10,7 +10,7 @@ on the "main" branch (which happens to be the default branch here).
 :::{objectives}
 - Record new changes to our own copy of the project.
 - Understand adding changes in two separate branches.
-- See how to compare different versions.
+- See how to compare different versions or branches.
 :::
 
 
@@ -50,7 +50,7 @@ Illustration of what we want to achieve in this exercise.
 :::{exercise} Exercise: Practice creating commits and branches (20 min)
 1. First create a new branch and then either add a new file or modify an
    existing file and commit the change.  Make sure that you now work **on your
-   copy** of the example repository. In your commit you can share a Git or
+   copy** of the example repository. In your new commit you can share a Git or
    programming trick you like.
 1. In a new commit, modify the file again.
 1. Switch to the `main` branch and create a commit there.
@@ -75,8 +75,8 @@ design.
 :::::{tabs}
 ::::{group-tab} GitHub
 1. Where it says "main" at the top left, click, enter a new branch
-   name `new-tutorial`, click on the offer to create the new branch
-   ("Create branch new-tutorial from main").
+   name (e.g. `new-tutorial`), then click on
+   "Create branch ... from main".
 1. Make sure you are still on the `new-tutorial` branch (it should say
    it at the top), and click "Add file" → "Create new file" from the
    upper right.
@@ -175,7 +175,7 @@ $ git commit -m "short summary of the change"
 
 ### (4) Browse the commits you just made
 
-Let's look at what we did.  Now, the `main` and `new-tutorial` branches
+Let's look at what we did.  Now, the `main` and the new branches
 have diverged: both have some modifications. Try to find the commits
 you created.
 
@@ -210,7 +210,7 @@ it makes sense later on.
 ::::{group-tab} GitHub
 A nice way to compare branches is to add `/compare` to the URL of the repository,
 for example (replace USER):
-`https://github.com/USER/planets/compare`
+https://github.com/**USER**/planets/compare
 ::::
 
 ::::{group-tab} VS Code
@@ -243,7 +243,7 @@ This is similar to above, but not only between branches.
 ::::{group-tab} GitHub
 Following the `/compare`-trick above, one can compare commits on GitHub by
 adjusting the following URL:
-`https://github.com/USER/planets/compare/VERSION1..VERSION2`
+https://github.com/**USER**/planets/compare/**VERSION1**..**VERSION2**
 
 Replace `USER` with your username and `VERSION1` and `VERSION2` with a commit hash or branch name.
 Please try it out.

content/version-control/browsing.md

@@ -97,8 +97,8 @@ Work on this by yourself or in pairs.
 In this case you will work on a fork.
 
 You only need to open your own view, as described above.  The browser
-URL should look like `https://github.com/USER/planets`, where
-`USER` is your GitHub username.
+URL should look like https://github.com/**USER**/planets, where
+USER is your GitHub username.
 ::::
 
 ::::{group-tab} VS Code
@@ -158,9 +158,9 @@ prepare questions.  The hints are for the GitHub path in the browser.
    (Hint: "History" button in the file view)
 1. **Which files include the word "position"**?
    (Hint: the GitHub search on top of the repository view)
-1. In the `simulate.py` file, find out **who modified each line last and when**
-   (click on file, then click "Blame" button). Find out who modified the gravitational constant
-   last and in which commit.
+1. In the `simulate.py` file,
+   find out who modified the "gravitational constant"
+   last and **in which commit**.
    (Hint: "Blame" view in the file view)
 1. Can you use this code yourself? **Are you allowed to share
    modifications**?
@@ -219,8 +219,8 @@ $ git log --oneline
 ### (2) Compare commit history with network graph
 
 The commit history we saw above looks linear: one commit after
-another.  But if we look at the network view, we see some branches and
-merges.  We'll see how to do these later.  This is another one of the
+another.  But if we look at the network view, we see some branching and merging points.
+We'll see how to do these later.  This is another one of the
 basic Git views.
 
 :::::{tabs}
@@ -288,8 +288,8 @@ $ git log simulate.py
 
 ### (4) Which files include the word "position"?
 
-Version control makes it very easy to find all occurrences of a single
-word. This is useful for things like finding where functions or
+Version control makes it very easy to find all occurrences of a
+word or pattern. This is useful for things like finding where functions or
 variables are defined or used.
 
 :::::{tabs}
@@ -324,7 +324,7 @@ $ git grep -i position       # case insensitive
 :::::
 
 
-### (5) Who modified each line last and when?
+### (5) Who modified a particular line last and when?
 
 This is called the "annotate" or "blame" view. The name "blame"
 is very unfortunate, but it is the standard term for historical reasons
@@ -334,7 +334,8 @@ for this functionality and it is not meant to blame anyone.
 
 ::::{group-tab} GitHub
 From a file view, change preview to "Blame" towards the top-left.
-To get the actual commit, click on the commit message.
+To get the actual commit, click on the commit message next
+to the code line that you are interested in.
 ::::
 
 ::::{group-tab} VS Code

content/version-control/merging.md

@@ -8,7 +8,7 @@ means that we have to somehow combine the changes later. In this part we will
 practice this: **merging**.
 
 :::{objectives}
-- Understand that on GitHub merging is done through a **pull request**. Think
+- Understand that on GitHub merging is done through a **pull request** (on GitLab: "merge request"). Think
   of it as a **change proposal**.
 - Create and merge a pull request within your own repository.
 - Understand (and optionally) do the same across repositories, to contribute to
@@ -105,8 +105,7 @@ frustrated because they forgot this!
 
 :::::{tabs}
 ::::{group-tab} GitHub
-GitHub will notice a recently changed branch and offer to make a pull request:
-merge **from**:
+GitHub will notice a recently changed branch and offer to make a pull request (clicking there will bring you to step 3):
    :::{figure} img/merging/github-compare-and-pr.png
    :alt: Screenshot on GitHub suggesting to compare and make a pull request.
    :width: 80%
@@ -333,15 +332,16 @@ $ git log --oneline
 
 ### (7) Contribute to the original repository with a pull request
 
-Remember, this is an advanced step.  We will practice this tomorrow.
+This is an advanced step. We will practice this tomorrow and
+it is OK to skip this at this stage.
 
 :::::{tabs}
 ::::{group-tab} GitHub
 Now that you know how to create branches and opening a pull request, try to
 open a new pull request with a new change but this time the base repository
 should be the upstream one.
 
-In other words, you now send a pull request across repositories: from your fork
+In other words, you now send a pull request **across repositories**: from your fork
 to the original repository.
 
 Another thing that is different now is that you might not have permissions to

content/version-control/motivation.md

@@ -7,7 +7,7 @@
 - Remember that commits are like **snapshots** of the repository at a certain
   point in time.
 - Know the difference between **Git** (something that tracks changes) and
-  **GitHub/GitLab** (a platform to host Git repositories).
+  **GitHub/GitLab** (a web platform to host Git repositories).
 :::
 
 
@@ -59,8 +59,8 @@ of them?):
 
 - **Branching and merging**:
   - Work on different ideas at the same time
-  - Different people can work on the same code/project without interfering
   - You can experiment with an idea and discard it if it turns out to be a bad idea
+  - Different people can work on the same code/project without interfering
 
 :::{figure} img/gophers.png
 :alt: Branching explained with a gopher

content/version-control/practical-advice.md

@@ -8,8 +8,8 @@
 Useful commit messages **summarize the change and provide context**.
 
 If you need a commit message that is longer than one line,
-then the convention is: **one line summarizing the commit, then one empty line,
-then paragraph(s) with more details in free form, if necessary**.
+then the convention is: one line summarizing the commit, then one empty line,
+then paragraph(s) with more details in free form, if necessary.
 
 Good example:
 ```{code-block} text
@@ -92,9 +92,9 @@ But remember: it is better to make any commit, than no commit. Especially in sma
 - Better too small than too large (easier to combine than to split).
 - Often I make a commit at the end of the day (this is a unit I would not like to lose).
 - Smaller sized commits may be easier to review for others than huge commits.
-- Imperfect commits are better than no commits.
 - A commit should not contain unrelated changes to simplify review and possible
   repair/adjustments/undo later (but again: imperfect commits are better than no commits).
+- Imperfect commits are better than no commits.
 
 
 ## Working on the command line? Use "git status" all the time
@@ -130,7 +130,7 @@ which files might not be tracked, etc.
   commits than no commits.
 
 - When working with branches:
+  - Working on unrelated things on the same branch.
   - Not updating your branch before starting new work.
   - Too ambitious branch which risks to never get completed.
-  - Over-engineering the branch layout and safeguards in small projects.
-  - Working on unrelated things on the same branch.
+  - Over-engineering the branch layout and safeguards in small projects -> can turn people away from your project.

content/version-control/sharing.md

@@ -22,7 +22,7 @@ From a bunch of files to a local repository which we then share on GitHub.
 
 :::::{exercise} Exercise: Turn your project to a Git repo and share it (20 min)
 
-1. Create a new directory called **myproject** with one or few files in it.
+1. Create a new directory called **myproject** (or a different name) with one or few files in it.
    This represents our own project. It is not yet a Git repository. You can try
    that with your own project or use a simple placeholder example.
 2. Turn this new directory into a Git repository.