re-arrange episodes to match our autumn 2025 plan; closes #51

bast · bast · commit 64b79ec919ef · 2025-10-19T14:39:43.000+02:00
diff --git a/content/exercise1.md b/content/exercise1.md
@@ -1,16 +1,34 @@
-# Optional home-/group work
+# Exercise 1
 
-:::{admonition} This is completely optional
-You can participate in the lesson without working on any of the tasks below.
 
-We share these for individuals and groups who would like to work on some of
-these in preparation of the lesson or independently of a CodeRefinery workshop
-with their study group.
-
-We might comment on the contributed solutions during the lesson
-but we will definitely do so in a constructive and positive way.
+:::{admonition} You can participate in two ways
+- Either by discussing with others and writing your own thoughts via collaborative notes
+- Or by coding
+- Or a mix of the two that is most meaningful for you or your group
 :::
 
+
+## Discussion track
+
+We share these questions in a common collaborative document:
+```
+A. What does "modular code development" mean for you?
+B. What best practices can you recommend to arrive at well structured,
+   modular code in your favourite programming language?
+C. What do you know now about programming that you wish somebody told you earlier?
+D. Do you design a new code project on paper before coding? Discuss pros
+   and cons.
+E. Do you build your code top-down (starting from the big picture) or bottom-up
+   (starting from components)? Discuss pros and cons.
+F. Would you prefer your code to be 2x slower if it was easier to read and understand?
+```
+
+They can be answered by individual learners but also discussed within an
+exercise group.
+
+
+## Coding track
+
 You can practice on our [exercise repository](https://github.com/coderefinery/modular-type-along-exercise) which contains:
 - Data set
 - Python notebook which works but is not super general
diff --git a/content/exercise2.md b/content/exercise2.md
@@ -1,5 +1,21 @@
-# Types of encapsulation
+# Exercise 2
 
+
+:::{admonition} You can participate in two ways
+- Either by discussing with others and writing your own thoughts via collaborative notes
+- Or by coding
+- Or a mix of the two that is most meaningful for you or your group
+:::
+
+
+## Discussion track
+
+The topic of this discussion session is encapsulation.
+Can you please comment on these recommendations in the collaborative notes and perhaps suggest
+other recommendations which have helped in your work and others could find useful?
+
+
+:::{discussion} Types of encapsulation
 Let's say you want to move a code from one system to another.  What are the things that can go wrong?
 
 - **In-language dependencies**, e.g. Python. Can they all be expressed *only* in
@@ -12,12 +28,21 @@ Let's say you want to move a code from one system to another.  What are the thin
 - Are you using something that is **OS-specific** (GNU/Linux vs BSD)?
 - Do you use support programs only available on certain computers?  Fewer
   external utilities you use = easier portability.
+:::
 
 
-## What needs to be global vs what needs to be local?
-
+:::{discussion} What needs to be global vs what needs to be local?
 - Global data can be "seen"/accessed in the entire code.
 - Local data is only available in the local vicinity of its definition.
 - Try to have as little global data as possible.
 - Global data are often input parameters, configuration parameters, command-line arguments.
 - But try to localize these to the "main" code/function.
+:::
+
+
+
+## Coding track
+
+Here you can continue either with some of the coding tasks from the first
+exercise session or you can program something inspired by our live-coding
+session.
diff --git a/content/index.md b/content/index.md
@@ -9,15 +9,30 @@ Image to get started:
 17(3): e1008549. <https://doi.org/10.1371/journal.pcbi.1008549>)
 
 
+## Timing overview
+
+:::{csv-table}
+:widths: auto
+:delim: ;
+
+20 min ; {doc}`starting-point`
+20 min ; {doc}`exercise1`
+10 min ; Discussion
+10 min ; Break
+30 min ; Live-coding with suggestions via notes ({doc}`solution`)
+20 min ; {doc}`exercise2`
+10 min ; Break
+15 min ; Discussion
+:::
+
+
 :::{toctree}
 :maxdepth: 1
-:caption: The lesson
+:caption: Episodes
 
-questions
-learning-outcomes
-lesson
-optional-homework
-encapsulation
+starting-point
+exercise1
+exercise2
 :::
 
 
diff --git a/content/learning-outcomes.md b/content/learning-outcomes.md
diff --git a/content/questions.md b/content/questions.md
diff --git a/content/solution.md b/content/solution.md
@@ -1,6 +1,4 @@
-(guide)=
-
-# An iterative solution
+# One possible solution
 
 ## Before we start
 
@@ -14,10 +12,7 @@ other languages in its place.
 We **collect ideas and feedback in the collaborative document while coding** and the instructor
 tries to react to that without going into the rabbit hole.
 
-We recommend to go through this together where the instructor(s) demonstrate(s)
-and learners can commend, suggest, and ask questions, and we are either all in
-the same video room or everybody is watching via stream. In other words, for
-this lesson, **learners are not in separate breakout-rooms**.
+Learners can also explore some of these steps in one of the exercise sessions.
 
 
 ## Checklist
diff --git a/content/starting-point.md b/content/starting-point.md
@@ -1,4 +1,4 @@
-# Our task
+# Starting with an example code in a Notebook
 
 
 ## Data
@@ -70,3 +70,23 @@ the ideas and steps in the {ref}`guide`.
 It is OK and good if mistakes happen and it is fun if the instructor(s) can
 convey a bit of "improv" feel to this lesson.
 :::
+
+
+## Learning outcomes
+
+- Know about **pure functions** (functions without side effects, functions which
+  given same input always return same output).
+- Learn why and how to **limit side effects** of functions.
+- Discuss why and how to limit side effects of data. Also discuss when
+  mutable data may be preferable.
+- [The Zen of Python](https://www.python.org/dev/peps/pep-0020/)
+- Discuss why **single-purpose functions** are often preferred over
+  multi-purpose functions.
+- **Split-apply-combine**, which lets you more easily parallelize. Make your code
+  modular in a way that lets you split the steps and parallelize.
+- Think about **global vs local** data structures. It is not easy to
+  separate them right.
+- Understand how a command line interface to a code can improve usability and also
+  make the code more versatile (to be combined with workflow management tools).
+- Connect modular code development to the remaining lessons (version control, testing,
+  documentation, reproducibility).
