carpentries-incubator · anenadic · Jan 27, 2026
diff --git a/episodes/00-setting-the-scene.md b/episodes/00-setting-the-scene.md
@@ -56,24 +56,18 @@ and sustain in the future by yourself and others.
 Skills and tools taught here, while Python-specific,
 are transferable to other similar tools and programming languages.
 
-The course is organised into the following sections:
-
-![Course overview diagram](fig/course-overview.svg){alt="Course overview diagram. Arrows connect the following boxed text in order: 1) Setting up software environment 2) Verifying software correctness 3) Software development as a process 4) Collaborative development for reuse 5) Managing software over its lifetime."}
-
-<!---
-Source of the above image can be rendered in the Mermaid live editor:
-<https://mermaid.live/edit#pako:eNpdkE1rwzAMhv-K8CmFNrCvSw6D9eO2XlbYYeSiJXJqcKwgKyml9L_PaZox5pOQn8ey3oupuCZTGOv5VB1RFN4_ygDpvGUPORxI1YUG-m5qRrZ6QiGgMDjh0FLQBZRhtXqFdfaYwyeJs-ek_OMrFqFKA8U485vsKQ2YgZoG8tyND8LkYgSETrganUnZZs85bNh7_GZBdQPd2b-2ZQGhPtJd2mUvOewxYDNu8vujSeSBBJxG8M6SupYWZmlakhZdnWK5jFRp9EgtlaZIZU0We6-lKcM1odgrH86hMoVKT0vTdzUqbR02gq0pLPqYulQ7ZdlPUd8Sn8nd7Wa2OwxfzLN3_QE4H4oo>
-
-The mermaid source is (with one less dash in arrows than needed):
-
+The course is organised into the following sections.
+<!-- 
+alt-tex="Course overview diagram. Arrows connect the following boxed text in order: 1) Setting up software environment 2) Verifying software correctness 3) Software development as a process 4) Collaborative development for reuse 5) Managing software over its lifetime."
+-->
 ```mermaid
-flowchart LR
-  A(1. Setting up software environment) -> B(2. Verifying software correctness)
-  B -> C(3. Software development as a process)
-  C -> D(4. Collaborative development for reuse)
-  D -> E(5. Managing software over its lifetime)
+    flowchart LR
+        accDescr {Overview of sections in the lesson: setting up development environment, verifying software correctness, the process of software development & engineering, collaborative software development, managing & maintaining software}
+        A(1. Setting up software environment) --> B(2. Verifying software correctness)
+        B --> C(3. Software development as a process)
+        C --> D(4. Collaborative development for reuse)
+        D --> E(5. Managing software over its lifetime)
 ```
--->
 
 ### [Section 1: Setting up Software Environment](10-section1-intro.md)
 

diff --git a/episodes/10-section1-intro.md b/episodes/10-section1-intro.md
@@ -31,27 +31,22 @@ As you get more comfortable with different tools and their alternatives,
 you will select the one that is right for you based on your personal preferences
 or based on what your collaborators are using.
 
-![Section 1 Overview](fig/section1-overview.svg){alt='Tools needed to collaborate on code development effectively'}
-
-<!---
-Source of the above image can be rendered in the Mermaid live editor:
-<https://mermaid.live/edit#pako:eNpdkttKAzEQhl9lyIVsoS14AtkLQW3RggVRUJC9GXdn20A2s0wmLSK-u0m3K2IuQpj83z-H5MvU3JApTet4X29RFB6fKw9p3RSnc3ghVes3EHsYooFb3aMQkN9ZYd-R18oPdzNYBXaoBOgbkOghm5dp77occdbTFBKmEd1fgwAnsFosw2jzShIsZ9yrsDvYhW3OOhjeW01E2h_ix8i8iU2J9-TcbJ-OSmP2p-XT1aTys9k13BZn82xu28_U1L-GahahWj2FMIFBf1ecpxGMgoZ25LjPBR-HgQEQeuE6MwOyKC7mcMfO4QcLqt3RUfuXbllAKAY6Qsvicg5r9LjJs_6taAB5RwI2zcjZltR2NDFT05F0aJv0cF9ZVRndUkeVKdOxoRaj08pU_jtJMSq_fPralCqRpib2TXqihcWNYGfKFl1IUWqssqyHz3D4E6NyebgZ6R79O_PIff8AoRHADA>
-
-The mermaid source (with one less dash in arrows than needed):
-
-flowchart LR
-  A(1. Setting up
-  software environment
-
-  - Isolate and run code: command line, virtual environment & IDE
-  - Version control and share code: Git & GitHub
-  - Write well-written code: PEP8)
-
-  A -> B(2. Verifying software correctness)
-  B -> C(3. Software development as a process)
-  C -> D(4. Collaborative development for reuse)
-  D -> E(5. Managing software over its lifetime)
+<!--
+alt = "Topics on effective collaborating on code development covered in the current section: virtual development environments, version control & sharing code, writing readable code & code standards"
+"
 -->
+```mermaid
+    flowchart LR
+        accDescr {Topics on effective collaborating on code development covered in the current section: virtual development environments, version control & sharing code, writing readable code & code standards}
+          A(1. Setting up software environment
+            - Isolating & running code: command line, virtual environment & IDE
+            - Version control and sharing code: Git & GitHub
+            - Well-written & readable code: PEP8)
+        A --> B(2. Verifying software correctness)
+        B --> C(3. Software development as a process)
+        C --> D(4. Collaborative development for reuse)
+        D --> E(5. Managing software over its lifetime)
+```
 
 Here is an overview of the tools we will be using.
 

diff --git a/episodes/14-collaboration-using-git.md b/episodes/14-collaboration-using-git.md
@@ -106,27 +106,20 @@ with different parts of the Git infrastructure, including:
   is to always do a `git pull` before a `git push`, to ensure you have any latest changes before you push your own.
 
 <!--
-Created with https://mermaid.live/edit#pako:eNqVUsFOwzAM_ZXIJxBldK3aZjlMQsANLhsSEuolNF5brU1KmgjKtH8nbRlsTEPCJ9t5L-9Z9gYyJRAYtPhqUWZ4W_Jc8zqVxMWT0utS5uRRI17O5xdLw_O-vtbIGclLQ7gQI3T_qYfeq4xXZIGNakujdDfCM1XXpRkZvxE9a4G1MnhEa2xbjKQjwGmtFZqsOC21PxsbvBWYrZU1_6DUqHP8w9gB4WuSqiJnbaG0yazzqPSPV1dVlXpDQV46su_oatA5Bw9cUvNSuH1tetkUTIE1psBcKnDFbWVSSOXWQbk1atnJDJjRFj2wjeBmt15gK161rouiN_sw3sBwCh5oZfPiG9Fw-axUffjN3UDb9XLdWxpzjVKgvlFWGmDxdOAD28A7sIhGkygJ_Wjm08APp4EHHbAknszCJAoCSumUhvHWg49Bz5_QJPJdRGEYz5IkpttPWWLlPg
-
-sequenceDiagram
-    Working Tree->>+Staging Area: git add
-    Staging Area->>+Local Repository: git commit
-    Local Repository->>+Remote Repository: git push
-    Remote Repository->>+Local Repository: git fetch
-    Local Repository->>+Working Tree:git checkout
-    Local Repository->>+Working Tree:git merge
-    Remote Repository->>+Working Tree: git pull (shortcut for git fetch followed by git checkout/merge)
+  alt='Development lifecycle with Git. The diagram shows four parts of the Git infrastructure: the working tree, staging area, local repository, and remote repository, alongside the Git commands that move files between them. git add moves files from the working tree to the staging area. git commit moves files from the staging area to the local repository. git push moves files from the local repository to the remote repository, while git fetch moves updates from the remote repository to the local repository. git checkout and git merge move files from the local repository to the working tree. git pull, a shortcut for git fetch followed by git checkout or git merge, moves files directly from the remote repository to the working tree.'
 -->
 
-<!--
-SVG of the diagram can be downloaded from:
-https://mermaid.ink/svg/pako:eNqFksFuwyAMhl8FcemmdS_AodKm7rZe2sOkKRcXnAQNcEaMpqjquw-SZZtUReEE9vfbP5iL1GRQKtnjZ8KgcW-hieCrIPJ6o_hhQyP2NqJmisPjbvdwYmhK8CkiKNFYFmDMxP9PFfSVNDhxxI56W-TiOULQ7aTS5L3lSbgAlhpH9MS4VKRLfTuVWOJWfdTIul21cfMUqmg9xgbX-9-Kf8w7J-76liLrlI1Q_DOUT87RFxpxHsRvq5EBseEIeqx4Hnts7uVWZsCDNXmWl-Koktyix0qqvDVYQ3JcySpcMwqJ6TQELRXHhFuZOgM8j16qGlyfo2jKPQ7T_xi_yUy-jJlZ3UF4J5p112_HVM9r
--->
-
-![Software development lifecycle with Git](fig/git-lifecycle.svg){
-  alt='Development lifecycle with Git. Four parts of Git infrastructure are represented: working tree, staging area, local repository and remote repository, and alongside this various git commands. git add is shown moving files from working tree to staging area. git commit is shown moving files from staging area to local repository. git push is shown moving files from local repository to remote repository and git fetch from remote repository to local repository. git checkout and git merge are both shown as moving files from local repository to working tree. git pull, a shortcut for git fetch followed by git checkout / merge, is shown moving files from remote repository to working tree.' 
-  .image-with-shadow width="600px"
-}
+```mermaid
+sequenceDiagram
+    accDescr {Basic development lifecycle with Git and commands for moving files between the Git infrastructure: working tree, staging area, local repository, and remote repository.}
+    Working Tree-->>+Staging Area: git add
+    Staging Area-->>+Local Repository: git commit
+    Local Repository-->>+Remote Repository: git push
+    Remote Repository-->>+Local Repository: git fetch
+    Local Repository-->>+Working Tree:git checkout
+    Local Repository-->>+Working Tree:git merge
+    Remote Repository-->>+Working Tree: git pull (shortcut for git fetch followed by git checkout/merge)
+```
 
 ## Checking-in Changes to Our Project
 

diff --git a/episodes/20-section2-intro.md b/episodes/20-section2-intro.md
@@ -33,27 +33,21 @@ so we should try and employ such practices early on.
 We will also make use of techniques and infrastructure that allow us to do this
 in a scalable, automated and more performant way as our codebase grows.
 
-![Section 2 Overview](fig/section2-overview.svg){alt='Tools for scaled software testing'}
-
-<!---
-Source of the above image can be rendered in the Mermaid live editor:
-
-<https://mermaid.live/edit#pako:eNpNUctqwzAQ_JVFJweSQF8XHwppEtpCc2lKD0WXjbx2RO1dI60dQsi_V07jUp3E7MwyM3syTgoyuSlrObg9BoW3d8uL7GYOW1L1XEHXWo5S6gEDAXHvg3BDrBPLs9kjPGW3c_ik4MtjYv-jOgmBnDLFaNkypDeDD4oKZcCGDhK-4wgvOpUGlQC5gOiwJtDETAtzWL5e0GevL90OFk698J9wRbuugiHE1c4yu0vWRw8F9VRLO9i1jBEQ2iAuObqyV9n9HJZS17iTgOp7svxPA6UECNTFcfs6e5jDBhmroZkxqmXpKYDXCLUvSX1DEzM1DYUGfZHaPQ12rdE9NWRNnr4FldjVao3lc6Jiyr89sjO5ho6mpmuL1MbKY5WqMnmJdUwoFV4lbH4vdjncyFxfJqO6Rf4SGXXnH1UppyA>
-
-The mermaid source (with one less dash in arrows than needed):
-
-flowchart LR
-  A(1. Setting up software environment)
-  A -> B(2. Verifying software correctness
-
-  - Test frameworks
-  - Automate and scale testing: CI and GitHub Actions
-  - Debug code)
-
-  B -> C(3. Software development as a process)
-  C -> D(4. Collaborative development for reuse)
-  D -> E(5. Managing software over its lifetime)
+<--
+alt="Topics on verifying software correctness covered in the current section: testing frameworks, automating and scaling up testing, and code debugging"
 -->
+```mermaid
+    flowchart LR
+        accDescr {Topics on verifying software correctness covered in the current section: testing frameworks, automating and scaling up testing, and code debugging}
+        A(1. Setting up software environment)
+        A --> B(2. Verifying software correctness:
+                - Testing frameworks
+                - Automating & scaling testing: CI and GitHub Actions
+                - Debugging code)
+        B --> C(3. Software development as a process)
+        C --> D(4. Collaborative development for reuse)
+        D --> E(5. Managing software over its lifetime)
+```
 
 In this section we will:
 

diff --git a/episodes/30-section3-intro.md b/episodes/30-section3-intro.md
@@ -21,30 +21,27 @@ exercises: 0
 In this section, we will take a step back from coding development practices and tools
 and look at the bigger picture of software as a *process* of development.
 
+<!--
+alt="Topics on software engineering process covered in the current section: gathering requirements, software architecture & design, programming paradigms"
+-->
+
+```mermaid
+    flowchart LR
+        accDescr {Topics on software engineering process covered in the current section: gathering requirements, software architecture & design, programming paradigms}
+        A(1. Setting up software environment)
+        A --> B(2. Verifying software correctness)
+        B --> C(3. Software development as a process
+            - Software requirements
+            - Software architecture & design
+            - Programming paradigms)
+        C --> D(4. Collaborative development for reuse)
+        D --> E(5. Managing software over its lifetime)
+```
+
 > *"If you fail to plan, you are planning to fail."* 
 > 
 > --- Benjamin Franklin
 
-![](fig/section3-overview.svg){alt='Software design and architecture overview flowchart'}
-
-<!---
-Source of the above image can be rendered in the Mermaid live editor:
-
-<https://mermaid.live/edit#pako:eNplkU1rwzAMhv-K8WGk0Ab2dclhsLW9rTBW2GH4oiVKakikTJZTSul_n9M122A-2dKj95Wsoy25QlvYuuV9uQNR8_zq6DG7zs0WVT01JvaOAte6B0GDNHhh6pB05mixeDBP2U1u3lB8fUj0H7RkESyVMIQLusxuk-yUr3DAlvtRyhEEA6YXLhPtyJFJZ_HLCn5GLziy4V8SpNx5TVYxPa6SbvDNj8SLcCPQdeMkPQhUvukuEpeuVtldbpbctvDBAuoHdPSnN1OzJP8Y8MKvs_vcbICgGTWncR3xgGK8BtP6GtV3OLNz26F04Kv0w8fR1FndpSmcLdK1whpiq846OiUUovL2QKUtVCLObewrUFx5GPu3RQ1tSFGsvLJsvrd2Xt5Ers-ZqboHemee6k5flmapmQ>
-
-The mermaid source (with one less dash in arrows than needed):
-
-flowchart LR
-  A(1. Setting up software environment)
-  A -> B(2. Verifying software correctness)
-  B -> C(3. Software development as a process
-  - Software requirements
-  - Software architecture & design
-  - Programming paradigms)
-  C -> D(4. Collaborative development for reuse)
-  D -> E(5. Managing software over its lifetime)
--->
-
 ## Writing Code vs Engineering Software
 
 Traditionally in academia, software - and the process of writing it -

diff --git a/episodes/40-section4-intro.md b/episodes/40-section4-intro.md
@@ -46,33 +46,19 @@ using **Poetry** to manage our Python dependencies
 and produce a code package we can use with a Python package indexing service
 to illustrate these principles.
 
-![](fig/section4-overview.svg){alt='Software design and architecture' .image-with-shadow width="1000px" }
-
-<!--
-Source of the above image can be rendered in the Mermaid live editor:
-
-https://mermaid.live/edit#pako:eNpVkE9rwzAMxb-K8CmFNrB_lxwGW9vbellhh-GLlsitIZGCrKSU0u8-t2vYpouF9HsP-Z1cLQ25yoVWDvUe1eDt3fNLcVfClswi72DoPScJdkAlIB6jCnfENvO8WDzDa3FfwgdpDMdM_0FrUaXamFK6ocviIdtO-4ZGaqW_WHnGBAi9Sv1Lr4rHEpbStvglihZH8vxHA0EUlIaUx54h1wL-vzefdfFUwgYZd5ffTOd5lpEUoiVoYyCLHc3c3HWkHcYmJ3K6mHhne-rIuyq3DQUcWvPO8zmjOJhsj1y7ynSguRv6Bo1WEXeKnasCtilPqYkmuvlJ-Rr2RK6vm0ndI3-KTLrzNzfGi8o
-
-The mermaid source (with one less dash in arrows than needed):
-
-flowchart LR
-A(1. Setting up
-software environment)
--> B(2. Verifying
-software correctness)
--> C(3. Software development
-as a process)
--> D(4. Collaborative
-development for reuse
-
-    - Code review
-    - Software documentation
-    - Software packaging & release
-    )
--> E(5. Managing software
-over its lifetime)
-
--->
+```mermaid
+    flowchart LR
+        accDescr {Topics on collaborative software development covered in the current section: code review, writing software documentation, packaging & releasing software}
+        A(1. Setting up software environment)
+        A --> B(2. Verifying software correctness)
+        B --> C(3. Software development as a process)
+        C --> D(4. Collaborative development for reuse
+        - Code review
+        - Software documentation
+        - Software packaging & release
+        )
+        D --> E(5. Managing software over its lifetime)
+```
 
 
 

diff --git a/episodes/41-code-review.md b/episodes/41-code-review.md
@@ -195,11 +195,12 @@ have not seen before.
 Here is an outline of the process of a tool assisted code review.
 
 <!--
+alt='Sequence diagram illustrating the code review process: a developer submits code, reviewer provides feedback and requests changes, revisions are made, and the code is approved and merged.'
+-->
 
 ```mermaid
-%% Must disable useMaxWidth to have the diagram centre
-%%{init: { 'sequence': {'useMaxWidth':false} } }%%
 sequenceDiagram
+    accDescr {Code review process: a developer submits code, reviewer provides feedback and requests changes, revisions are made, and the code is approved and merged}
     participant A as Author
     participant R as Reviewer
     A->>A: Write some code
@@ -214,11 +215,6 @@ sequenceDiagram
     A->>A: Merge pull request
 ```
 
-Generated with Mermaid tool, diagram available at: <https://mermaid.live/edit#pako:eNptUrtuwzAM_BVCgOEl_QEPAYx29eKgyOKFsZhYgF6VKLeBkX-vXDvNo5UWSXfHI0VOoneSRCWKApoUGaSKeNAEKVKDX3sleQB2MOBIwANlHE8BDfRkOVBni2JSVnEFE5SRPhLZnsp8K-8ClNURdaQL5F0Unb3y3pZYnYW8PAZWvfJoGWrACHXiwYW_YDuDLY2KPmmF65fttq5gHxQTRGcI5qpuWFtBiyoSIPikNYQ5gcgLoV0ItZRZZUyuK84VY2bNHjdSdtilg1H8hGnnPLxbVhrQ--BGkgtwZ5-jB4oRXMjS6J2Vs8cS5df2plrtXjUGdTyvKqdHeuKSlQ_51Yv_P1WuX9RQOD3CYiMMBYNK5imYZnIncqMNdaLKR0lHTJo70dlLpmJitzvbXlQcEm1E8hL52sjrI0nFLjTLYP3M1-Ub_pDLrQ>
--->
-
-![](fig/code-review-sequence-diagram.svg){alt='Code review process sequence' .image-with-shadow width="600px"}
-
 Recall [solution requirement SR1.1.1](31-software-requirements.md)
 from an earlier episode.
 A fictional colleague has implemented it according to the specification

diff --git a/episodes/50-section5-intro.md b/episodes/50-section5-intro.md
@@ -30,33 +30,22 @@ how the outside world interacts with and makes use of our software,
 how others can interact with ourselves to report issues,
 and the ways we can successfully manage software improvement in response to feedback.
 
-![](fig/section5-overview.svg){alt='Managing software' .image-with-shadow width="1000px" }
-
-<!-- 
-Source of the above image can be rendered in the Mermaid live editor:
-
-https://mermaid.live/edit#pako:eNpNkMtqw0AMRX9FzMqBxNDXxotCm2TXbBroosxGtTXJgC0ZjewQQv69k4dpF0JCOvci7snV0pCrXGjlUO9RDT4-Pb8VDyVsySzyDobec5JgB1QC4jGqcEdsM8-LxSu8F48lfJHGcMz0P7QWVaqNKaU7uiyesu10b2ikVvqLlWdMgNCr1H_0qnguYSltiz-iaHEkz_80EERBaUh059fFSwkbZNxdvp7e8CwjKURL0MZAFru8ygLIdWszN3cdaYexyUGcPAN4Z3vKoKvy2FDAoTXvPJ8zioPJ9si1q0wHmruhb9BoFXGn2LkqYJvylppooptbuNeMJ3J9vUzqHvlbZNKdfwFSLYtB
-
-The mermaid source (with one less dash in arrows than needed):
-
-flowchart LR
-A(1. Setting up
-software environment)
--> B(2. Verifying
-software correctness)
--> C(3. Software development
-as a process)
--> D(4. Collaborative
-development for reuse)
--> E(5. Managing software
-over its lifetime
-
-    - Issue reporting & prioritisation
-    - Agile development in sprints
-    - software project management
-)
-
+<!--
+alt="Topics on collaborative software development covered in the current section: issue management, project management, agile development"
 -->
+```mermaid
+    flowchart LR
+        accDescr {Topics on collaborative software development covered in the current section: issue management, project management, agile development}
+        A(1. Setting up software environment)
+        A --> B(2. Verifying software correctness)
+        B --> C(3. Software development as a process)
+        C --> D(4. Collaborative development for reuse)
+        D --> E(5. Managing software over its lifetime
+
+            - Issue reporting & prioritisation
+            - Agile development in sprints
+            - Software project management)
+```
 
 In this section we will: