From ddf1fa89280f0174abe995418e663887507d0e02 Mon Sep 17 00:00:00 2001
From: GitHub Actions <actions@github.com>
Date: Thu, 12 Sep 2024 13:42:08 +0000
Subject: [PATCH] site deploy

Auto-generated via {sandpaper}
Source  : c2746f74dfa599c291d3a4550449f794da95ede2
Branch  : md-outputs
Author  : GitHub Actions <actions@github.com>
Time    : 2024-09-12 13:41:53 +0000
Message : markdown source builds

Auto-generated via {sandpaper}
Source  : 8f62e1d890d5ec1525d6b95099850d20526d95e8
Branch  : main
Author  : Joe Heffer <60133133+Joe-Heffer-Shef@users.noreply.github.com>
Time    : 2024-09-12 13:40:59 +0000
Message : Merge pull request #43 from Joe-Heffer-Shef/28-ep-2-readmes-improvements

Episode 2 tweaks
---
 aio.html                     | 259 +++++++++++++++++++++++------------
 cli.html                     |  32 ++---
 docstrings.html              |  16 +--
 index.html                   |   6 +-
 instructor/aio.html          | 259 +++++++++++++++++++++++------------
 instructor/cli.html          |  32 ++---
 instructor/docstrings.html   |  16 +--
 instructor/index.html        |   6 +-
 instructor/introduction.html |  10 +-
 instructor/key-points.html   |   5 -
 instructor/readmes.html      | 204 ++++++++++++++++++---------
 introduction.html            |  10 +-
 key-points.html              |   5 -
 md5sum.txt                   |   2 +-
 pkgdown.yml                  |   2 +-
 readmes.html                 | 204 ++++++++++++++++++---------
 16 files changed, 692 insertions(+), 376 deletions(-)

diff --git a/aio.html b/aio.html
index 4551377..5f73866 100644
--- a/aio.html
+++ b/aio.html
@@ -501,7 +501,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Python" class="tab-pane show active" aria-labelledby="nav-tab-1-Python" role="tabpanel">
+<div id="nav-tabpanel-1-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Python">
 <p>This is some research code that is contained in a Python
 function.</p>
 <div class="codewrapper sourceCode" id="cb1">
@@ -512,7 +512,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a>  <span class="cf">return</span> x <span class="op">*</span> weird_num <span class="op">-</span> angle<span class="op">**</span><span class="dv">3</span> <span class="op">/</span> (weird_num <span class="op">*</span> <span class="dv">2</span>)</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-R" class="tab-pane" aria-labelledby="nav-tab-1-R" role="tabpanel">
+<div id="nav-tabpanel-1-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-R">
 <p>This is some research code that is contained in an R function.</p>
 <div class="codewrapper sourceCode" id="cb2">
 <h3 class="code-label">R<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
@@ -576,7 +576,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-Challenge">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Python" class="tab-pane show active" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <p>This is a function written in the Python programming language that
 calculates a mathematical result, the details of which aren’t relevant.
 This code has plenty of documentation to help us read and understand
@@ -612,7 +612,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb3-26"><a href="#cb3-26" tabindex="-1"></a>  <span class="cf">return</span> sin_value</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-R" class="tab-pane" aria-labelledby="nav-tab-2-R" role="tabpanel">
+<div id="nav-tabpanel-2-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-R">
 <p>This is a function written in the R programming language that
 calculates a mathematical result, the details of which aren’t relevant.
 This code has plenty of documentation to help us read and understand it.
@@ -652,7 +652,7 @@ <h3 class="code-label">R<i aria-hidden="true" data-feather="chevron-left"></i><i
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 </div>
-<div id="nav-tabpanel-2-Python" class="tab-pane" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <p>Read and evaluate this code.</p>
 <ul>
 <li>Can you tell what the purpose of the function is?</li>
@@ -778,7 +778,7 @@ <h3 class="callout-title">Key Points</h3>
 </div>
 </section></section><section id="aio-readmes"><p>Content from <a href="readmes.html">Writing README files</a></p>
 <hr>
-<p>Last updated on 2024-07-22 |
+<p>Last updated on 2024-09-12 |
 
         <a href="https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/edit/main/episodes/readmes.md" class="external-link">Edit this page <i aria-hidden="true" data-feather="edit"></i></a></p>
 <div class="text-end">
@@ -888,7 +888,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Windows">
+<div id="nav-tabpanel-1-Windows" class="tab-pane show active" aria-labelledby="nav-tab-1-Windows" role="tabpanel">
 <ol style="list-style-type: decimal">
 <li>Open <a href="https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1" class="external-link">File
 Explorer</a> to browse the file system;</li>
@@ -900,7 +900,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 <li>Double-click on the file to open it for editing.</li>
 </ol>
 </div>
-<div id="nav-tabpanel-1-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-Linux">
+<div id="nav-tabpanel-1-Linux" class="tab-pane" aria-labelledby="nav-tab-1-Linux" role="tabpanel">
 <p>Use the <a href="https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en" class="external-link">File
 Manager</a> to create a new directory called <code>oddsong</code>.
 Inside that folder, create a new text file called
@@ -915,7 +915,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a><span class="fu">nano</span> oddsong/README.txt</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-MacOS">
+<div id="nav-tabpanel-1-MacOS" class="tab-pane" aria-labelledby="nav-tab-1-MacOS" role="tabpanel">
 <p>Use the <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac" class="external-link">Finder</a>
 file manager to create a new directory called <code>oddsong</code>.
 Inside that folder, create a new text file called
@@ -938,35 +938,38 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 </div>
 <p>The essentials contents of a README file are:</p>
 <ul>
-<li>The name of the software. This seems trivial, but a clear title and
-description of a piece of software will be essential for others to
-identify your software and differentiate it from others.</li>
-<li>A brief introduction to your code, including links to relevant
-websites or contact details for the maintainers. - It should be clear
-who the target audience is for the software package.</li>
-<li>Installation instructions or a link to further information published
-elsewhere.</li>
-<li>Usage instructions, ideally including a “quick start” guide with a
-few simple examples to get people up and running with your software
-package.</li>
+<li>The <strong>name of the software</strong>. This seems trivial, but a
+clear title and description of a piece of software will be essential for
+others to identify your software and differentiate it from others.</li>
+<li>A <strong>brief introduction</strong> to your code, including links
+to relevant websites or contact details for the maintainers.</li>
+<li>It should be clear who the <strong>target audience</strong> is for
+the software package.</li>
+<li>
+<strong>Installation instructions</strong> or a link to further
+information published elsewhere.</li>
+<li>
+<strong>Usage instructions</strong>, ideally including a “quick
+start” guide with a few simple examples to get people up and running
+with your software package.</li>
 </ul>
 <p>It can be useful to signpost to other, related useful software tools
 by providing links and explaining how other software is related or
 different to this project when it comes to addressing these kinds of
 research problems.</p>
-<div id="callout1" class="callout">
+<div id="walk-a-mile-in-the-users-shoes" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="walk-a-mile-in-the-users-shoes" class="callout-inner">
+<h3 class="callout-title">Walk a mile in the user’s shoes</h3>
 <div class="callout-content">
-<p>Put yourself in the shoes of a researcher who has encountered your
+<p>Put yourself in the position of a researcher who has encountered your
 software for the first time. Consider, if you had to start from square
-one, how would you like the code to be introduced to you? Remember:
-things that are obvious to you and your colleagues may not be clear to
-others. What assumed knowledge must you explicitly explain to get them
-up to speed?</p>
+one, how would you like the code to be introduced to you?</p>
+<p>Remember: things that are obvious to you and your colleagues may not
+be clear to others. What <strong>assumed knowledge</strong> must you
+explicitly explain to get them up to speed?</p>
 </div>
 </div>
 </div>
@@ -990,7 +993,7 @@ <h3 id="installation-instructions">Installation instructions<a class="anchor" ar
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 <div class="callout-inner">
-<h3 class="callout-title">Challenge</h3>
+<h3 class="callout-title">Discussion</h3>
 <div class="callout-content">
 <p>Consider a research code project you’ve worked on. Discuss the
 technical prerequisites for that software or system. What would someone
@@ -1029,18 +1032,21 @@ <h3 id="user-guide">User guide<a class="anchor" aria-label="anchor" href="#user-
 <p>Many users will benefit from a frequently asked questions (FAQ) or
 troubleshooting notes, which describes common error messages, explains
 why they occur, and the steps to resolve them.</p>
-<div id="callout2" class="callout">
+<div id="writing-style" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="writing-style" class="callout-inner">
+<h3 class="callout-title">Writing style</h3>
 <div class="callout-content">
-<p>The writing style should be concise, jargon-free, clear, and pitched
-at the appropriate level to the intended target audience. All technical
-terms and acronyms should be explained. However, don’t reinvent the
-wheel by defining all the terms used, instead link to a reliable
-external source or journal article.</p>
+<p>The writing style should be concise, jargon-free, consistent, and
+pitched at the appropriate level to the intended target audience. All
+technical terms and acronyms should be explained. However, don’t
+reinvent the wheel by defining all the terms used, instead link to a
+reliable external source or journal article.</p>
+<p>For more information about good writing style, please refer to these
+<a href="https://www.writethedocs.org/guide/writing/style-guides/#traditional-writing-style-guide-resources" class="external-link">style
+guides</a>.</p>
 </div>
 </div>
 </div>
@@ -1052,7 +1058,7 @@ <h3 class="callout-title">Callout</h3>
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 <div class="callout-inner">
-<h3 class="callout-title">Challenge</h3>
+<h3 class="callout-title">Discussion</h3>
 <div class="callout-content">
 <p>Discuss with the group:</p>
 <ul>
@@ -1066,6 +1072,8 @@ <h3 class="callout-title">Challenge</h3>
 </div>
 </div>
 </div>
+<p>Not all READMEs must follow this structure. Always adapt the format
+of your documentation to suit the specific needs of your audience.</p>
 </div>
 </section><section><h2 class="section-heading" id="markdown-format">Markdown format<a class="anchor" aria-label="anchor" href="#markdown-format"></a>
 </h2>
@@ -1073,12 +1081,36 @@ <h3 class="callout-title">Challenge</h3>
 <p>Most people prefer to use a file format that allows you to create
 headers to organise the content into sections or chapters, which is much
 clearer for the reader.</p>
-<p>In this case, a Markdown document may be used. Markdown is a simple
-mark-up language that allows you to format your text using symbols to
-represent headers, bold text, bullet lists, etc. that are displayed to
-the user in an appealing way. The Markdown syntax will be converted into
-appealing visual styles that make your documentation more aesthetically
-pleasing and easier to read.</p>
+<p>In this case, a <a href="https://daringfireball.net/projects/markdown/" class="external-link">Markdown</a>
+document may be used. Markdown is a simple <em>markup language</em> that
+allows you to format your text using symbols to represent headers, bold
+text, bullet lists, etc. that are displayed to the user in an appealing
+way. The Markdown syntax will be converted into appealing visual styles
+that make your documentation more aesthetically pleasing and easier to
+read.</p>
+<div id="accordionSpoiler1" class="accordion spoiler-accordion accordion-flush">
+<div class="accordion-item">
+<button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
+  <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> What is a markup language? </h3>
+</button>
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
+<div class="accordion-body">
+<p>A <a href="https://en.wikipedia.org/wiki/Markup_language" class="external-link">markup
+language</a> is a system of special characters that are used to
+<em>decorate</em> or <em>format</em> pieces of <em>plain text</em>. The
+syntax normally consists of symbols or <em>tags</em> that are used to
+<em>encode</em> text, which means <em>implying meaning</em> to make it
+more information-rich. It can be used to structure a documented into
+sections to provide logical organisation so that it’s easier to
+navigate.</p>
+<p>Typically, a markup language is edited in a similar way to a computer
+programming language, and is <strong>rendered</strong> into a document
+with various rich text formatting such as headers, bold face fonts,
+etc.</p>
+</div>
+</div>
+</div>
+</div>
 <div id="challenge2" class="callout challenge">
 <div class="callout-square">
 <i class="callout-icon" data-feather="zap"></i>
@@ -1119,7 +1151,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Windows">
+<div id="nav-tabpanel-2-Windows" class="tab-pane show active" aria-labelledby="nav-tab-2-Windows" role="tabpanel">
 <p>Use <a href="https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1" class="external-link">File
 Explorer</a> to <a href="https://support.microsoft.com/en-gb/office/rename-a-file-baea7aab-760b-4ee0-af58-06e940d505a4" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -1129,7 +1161,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 <li>Type <code>README.md</code>.</li>
 </ol>
 </div>
-<div id="nav-tabpanel-2-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Linux">
+<div id="nav-tabpanel-2-Linux" class="tab-pane" aria-labelledby="nav-tab-2-Linux" role="tabpanel">
 <p>Use the <a href="https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en" class="external-link">File
 Manager</a> to <a href="https://help.ubuntu.com/stable/ubuntu-help/files-rename.html.en" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -1140,7 +1172,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <pre class="sourceCode bash" tabindex="0"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="fu">mv</span> README.txt README.md</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-MacOS">
+<div id="nav-tabpanel-2-MacOS" class="tab-pane" aria-labelledby="nav-tab-2-MacOS" role="tabpanel">
 <p>Use the <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac" class="external-link">Finder</a>
 to <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp1144/mac" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -1305,6 +1337,50 @@ <h3 id="text-formatting">Text formatting<a class="anchor" aria-label="anchor" hr
 </tr>
 </tbody>
 </table>
+<p>These may be used to add emphasis to parts of the text or highligh
+key words and phrases. Using text formatting makes your software
+documentation easier to skim-read, so researchers can quickly find the
+part of the text that’s relevant for what they’re working on.</p>
+<div id="challenge4" class="callout challenge">
+<div class="callout-square">
+<i class="callout-icon" data-feather="zap"></i>
+</div>
+<div class="callout-inner">
+<h3 class="callout-title">Challenge</h3>
+<div class="callout-content">
+<p>Identify several <em>key words</em> in your README file. Highlight
+them in using a bold font face.</p>
+</div>
+</div>
+</div>
+<div id="accordionSolution4" class="accordion challenge-accordion accordion-flush">
+<div class="accordion-item">
+<button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution4" aria-expanded="false" aria-controls="collapseSolution4">
+  <h4 class="accordion-header" id="headingSolution4"> Show me the solution </h4>
+</button>
+<div id="collapseSolution4" class="accordion-collapse collapse" aria-labelledby="headingSolution4" data-bs-parent="#accordionSolution4">
+<div class="accordion-body">
+<p>The Markdown syntax for bold font is to wrap the text in two
+asterixes <code>**</code>. This may be applied to single words or to
+phrases.</p>
+<p>For example:</p>
+<div class="codewrapper sourceCode" id="cb8">
+<h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
+</h3>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a>Identify a bird based on the **sound** of its call.</span></code></pre>
+</div>
+<p>Identify a bird based on the <strong>sound</strong> of its call.</p>
+<div class="codewrapper sourceCode" id="cb9">
+<h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
+</h3>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb9-1"><a href="#cb9-1" tabindex="-1"></a>**Identify a bird** based on the _sound of its call_.</span></code></pre>
+</div>
+<p><strong>Identify a bird</strong> based on the <em>sound of its
+call</em>.</p>
+</div>
+</div>
+</div>
+</div>
 </div>
 <div class="section level3">
 <h3 id="block-quotes">Block quotes<a class="anchor" aria-label="anchor" href="#block-quotes"></a>
@@ -1312,10 +1388,10 @@ <h3 id="block-quotes">Block quotes<a class="anchor" aria-label="anchor" href="#b
 <p>We can create a citation with appealing formatting by using the
 blockquote syntax in Markdown, which is similar to the method used in
 email.</p>
-<div class="codewrapper sourceCode" id="cb8">
+<div class="codewrapper sourceCode" id="cb10">
 <h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
 </h3>
-<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a><span class="at">&gt; This text is part of a blockquote.</span></span></code></pre>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb10-1"><a href="#cb10-1" tabindex="-1"></a><span class="at">&gt; This text is part of a blockquote.</span></span></code></pre>
 </div>
 <p>This will be rendered with the following apperearance:</p>
 <blockquote>
@@ -1331,22 +1407,25 @@ <h3 id="code-blocks">Code blocks<a class="anchor" aria-label="anchor" href="#cod
 <p><code></code></p>
 <pre><code><span><span class="va">pi</span> <span class="op">=</span> <span class="fl">3.14</span></span></code></pre>
 <p></p>
-<div id="callout3" class="callout">
+<div id="markdown" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="markdown" class="callout-inner">
+<h3 class="callout-title">Markdown</h3>
 <div class="callout-content">
 <p>You can learn more about writing documents using Markdown at <a href="https://www.markdownguide.org/" class="external-link">Markdown Guide</a>, a reference
 for using this syntax.</p>
 </div>
 </div>
 </div>
-<p>Remember, the README file is a first impression that research users
-will receive for your software. Make them informative and user-friendly
-to enhance the research experience for others and foster
-collaboration.</p>
+<p>Remember, the README file is a <strong>first impression</strong> that
+research users will receive for your software. A README contains a brief
+description of the software, installation instructions, and a usage
+guide. Make them informative and user-friendly to enhance the research
+experience for others and foster collaboration. The writing style should
+be concide, clear, and explain technical terms. Use diagrams and
+screenshots for clarity.</p>
 <div id="keypoints1" class="callout keypoints">
 <div class="callout-square">
 <i class="callout-icon" data-feather="key"></i>
@@ -1359,23 +1438,27 @@ <h3 class="callout-title">Key Points</h3>
 users on installation, usage, and understanding its capabilities.</li>
 <li>Consider the user’s technical background; write clearly and avoid
 jargon.</li>
-<li>A README contains a brief description of the software, installation
-instructions, and a usage guide.</li>
-<li>The writing style should be concide, clear, and explain technical
-terms.</li>
-<li>Use diagrams and screenshots for clarity.</li>
 <li>Markdown is a recommended format for creating headers, bold text,
 bullet points, etc.</li>
 </ul>
 </div>
 </div>
 </div>
+</div>
+</section><section><h2 class="section-heading" id="further-resources">Further resources<a class="anchor" aria-label="anchor" href="#further-resources"></a>
+</h2>
+<hr class="half-width">
+<p>For more information about writing basic software documentation,
+please review the following materials:</p>
+<ul>
+<li>Raphael Pierzina <a href="https://www.writethedocs.org/videos/eu/2017/hi-my-name-is-readme-raphael-pierzina/" class="external-link">Hi,
+my name is README!</a>
+</li>
+</ul>
 <!--
 Place links that you need to refer to multiple times across pages here. Delete
 any links that you are not going to use.
- -->
-</div>
-</section></section><section id="aio-docstrings"><p>Content from <a href="docstrings.html">Documentation strings</a></p>
+ --></section></section><section id="aio-docstrings"><p>Content from <a href="docstrings.html">Documentation strings</a></p>
 <hr>
 <p>Last updated on 2024-09-12 |
 
@@ -1455,7 +1538,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Python" class="tab-pane show active" aria-labelledby="nav-tab-1-Python" role="tabpanel">
+<div id="nav-tabpanel-1-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Python">
 <p>In Python, we put a string as the first line of a function (or other
 object.) For example, for a simple Python function that calculates the
 sum of two numbers:</p>
@@ -1469,7 +1552,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a>    <span class="cf">return</span> x <span class="op">+</span> y</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-R" class="tab-pane" aria-labelledby="nav-tab-1-R" role="tabpanel">
+<div id="nav-tabpanel-1-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-R">
 <p>In R, we use a comment with a single quote <code>#'</code> to specify
 a documentation string for a function.</p>
 <div class="codewrapper sourceCode" id="cb2">
@@ -1507,7 +1590,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution1" aria-expanded="false" aria-controls="collapseSolution1">
   <h4 class="accordion-header" id="headingSolution1"> Show me the solution </h4>
 </button>
-<div id="collapseSolution1" class="accordion-collapse collapse" data-bs-parent="#accordionSolution1" aria-labelledby="headingSolution1">
+<div id="collapseSolution1" class="accordion-collapse collapse" aria-labelledby="headingSolution1" data-bs-parent="#accordionSolution1">
 <div class="accordion-body">
 <div class="tabs">
 <nav><div id="nav-tab-2" class="nav nav-tabs" role="tablist">
@@ -1523,7 +1606,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Python" class="tab-pane show active" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <ol style="list-style-type: decimal">
 <li>Create a new Python script by creating a file called
 <code>oddsong.py</code>;</li>
@@ -1544,7 +1627,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb3-8"><a href="#cb3-8" tabindex="-1"></a>    <span class="cf">return</span> <span class="st">"Hirundo atrocaerulea"</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-R" class="tab-pane" aria-labelledby="nav-tab-2-R" role="tabpanel">
+<div id="nav-tabpanel-2-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-R">
 <ol style="list-style-type: decimal">
 <li>Create a new R script by creating a file called
 <code>oddsong.R</code>;</li>
@@ -1601,7 +1684,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution2" aria-expanded="false" aria-controls="collapseSolution2">
   <h4 class="accordion-header" id="headingSolution2"> Show me the solution </h4>
 </button>
-<div id="collapseSolution2" class="accordion-collapse collapse" data-bs-parent="#accordionSolution2" aria-labelledby="headingSolution2">
+<div id="collapseSolution2" class="accordion-collapse collapse" aria-labelledby="headingSolution2" data-bs-parent="#accordionSolution2">
 <div class="accordion-body">
 <p>Let’s view the help text for an in-built <a href="https://docs.python.org/3/library/functions.html#abs" class="external-link">function
 <code>abs()</code></a> that finds the absolute value of a number.</p>
@@ -1714,7 +1797,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
   <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Using docstrings to create automatic tests </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
 <div class="accordion-body">
 <p>These code examples can be used as automatic tests using the <a href="https://docs.python.org/3/library/doctest.html" class="external-link">doctest</a> module
 which is built into Python.</p>
@@ -1748,7 +1831,7 @@ <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler2" aria-expanded="false" aria-controls="collapseSpoiler2">
   <h3 class="accordion-header" id="headingSpoiler2">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Docstring conventions </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
 <div class="accordion-body">
 <p>There are several different <strong>standards</strong> for
 documentation strings. A standard is a convention that determines how
@@ -3411,7 +3494,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Windows">
+<div id="nav-tabpanel-1-Windows" class="tab-pane show active" aria-labelledby="nav-tab-1-Windows" role="tabpanel">
 <p>On Windows operating systems, press the Windows key and type in
 “command”. The start menu will find the “Command Prompt” app. Press
 <kbd>Enter</kbd> or click on the Command Prompt icon to launch the
@@ -3431,7 +3514,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <p>For more information, see the <a href="https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands" class="external-link">Windows
 Commands</a> page on the Windows Server documentation.</p>
 </div>
-<div id="nav-tabpanel-1-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-Linux">
+<div id="nav-tabpanel-1-Linux" class="tab-pane" aria-labelledby="nav-tab-1-Linux" role="tabpanel">
 <p>On Ubuntu, press <kbd>Ctrl + Alt + T</kbd> to open a terminal.</p>
 <p>You can also open Dash and search for “Terminal”. For detailed
 instructions, please read <a href="https://ubuntu.com/tutorials/command-line-for-beginners#3-opening-a-terminal" class="external-link">Opening
@@ -3446,7 +3529,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <pre class="sourceCode bash" tabindex="0"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a><span class="ex">bob@myUbuntuPC:~$</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-MacOS">
+<div id="nav-tabpanel-1-MacOS" class="tab-pane" aria-labelledby="nav-tab-1-MacOS" role="tabpanel">
 <p>Please read <a href="https://support.apple.com/en-gb/guide/terminal/apd5265185d-f365-44cb-8b09-71a064a42125/mac" class="external-link">Open
 or quit Terminal on Mac</a> on the <a href="https://support.apple.com/en-gb/guide/terminal/welcome/mac" class="external-link">Terminal
 User Guide</a> for macOS.</p>
@@ -3480,7 +3563,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Windows">
+<div id="nav-tabpanel-2-Windows" class="tab-pane show active" aria-labelledby="nav-tab-2-Windows" role="tabpanel">
 <p>On Windows, the <a href="https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/dir" class="external-link">dir</a>
 command is used to list the contents of a directory. When you enter this
 command and press <kbd>Enter</kbd></p>
@@ -3510,7 +3593,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 file was last modified is shown, along with the file size, which is 12
 bytes in this case.</p>
 </div>
-<div id="nav-tabpanel-2-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Linux">
+<div id="nav-tabpanel-2-Linux" class="tab-pane" aria-labelledby="nav-tab-2-Linux" role="tabpanel">
 <p>To show the contents of a directory on a Linux system, we use the <a href="https://manpages.ubuntu.com/manpages/noble/man1/ls.1plan9.html" class="external-link"><code>ls</code>
 command</a> which lists information about the files in the current
 location.</p>
@@ -3527,7 +3610,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 <pre class="output" tabindex="0"><code><span><span class="va">README.txt</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-MacOS">
+<div id="nav-tabpanel-2-MacOS" class="tab-pane" aria-labelledby="nav-tab-2-MacOS" role="tabpanel">
 <p>The macOS terminal is very similar to the Linux one. To show the
 contents of a directory on a Linux system, we use the <a href="https://support.apple.com/en-gb/guide/terminal/apdb66b5242-0d18-49fc-9c47-a2498b7c91d5/2.14/mac/14.0" class="external-link"><code>ls</code>
 command</a> which lists information about the files in the current
@@ -3560,7 +3643,7 @@ <h3 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#argumen
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
   <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> What are arguments? </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
 <div class="accordion-body">
 <p>When using shell commands, we use the words <strong>option</strong>,
 <strong>flag</strong>, and <strong>arguments</strong> to describe
@@ -3589,7 +3672,7 @@ <h3 class="tab-header" id="nav-tab-heading-3-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-3" class="tab-content">
-<div id="nav-tabpanel-3-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-3-Windows">
+<div id="nav-tabpanel-3-Windows" class="tab-pane show active" aria-labelledby="nav-tab-3-Windows" role="tabpanel">
 <p>In the Windows command line, we use the <code>/?</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>dir</code>
@@ -3624,7 +3707,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 instructions for using it, and a reference to each of the options or
 arguments available.</p>
 </div>
-<div id="nav-tabpanel-3-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-3-Linux">
+<div id="nav-tabpanel-3-Linux" class="tab-pane" aria-labelledby="nav-tab-3-Linux" role="tabpanel">
 <p>In the Linux command line, we use the <code>--help</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>ls</code>
@@ -3653,7 +3736,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 instructions for using it, and a reference to each of the options or
 arguments available.</p>
 </div>
-<div id="nav-tabpanel-3-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-3-MacOS">
+<div id="nav-tabpanel-3-MacOS" class="tab-pane" aria-labelledby="nav-tab-3-MacOS" role="tabpanel">
 <p>In the macOS command line, we use the <code>--help</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>ls</code>
@@ -3705,7 +3788,7 @@ <h3 id="getting-started">Getting started<a class="anchor" aria-label="anchor" hr
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler2" aria-expanded="false" aria-controls="collapseSpoiler2">
   <h3 class="accordion-header" id="headingSpoiler2">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Why must our file be named __main__.py? </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
 <div class="accordion-body">
 <p>This is a mechanism that tells Python how we want users to interact
 with our software.</p>
@@ -3750,7 +3833,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution1" aria-expanded="false" aria-controls="collapseSolution1">
   <h4 class="accordion-header" id="headingSolution1"> Show me the solution </h4>
 </button>
-<div id="collapseSolution1" class="accordion-collapse collapse" data-bs-parent="#accordionSolution1" aria-labelledby="headingSolution1">
+<div id="collapseSolution1" class="accordion-collapse collapse" aria-labelledby="headingSolution1" data-bs-parent="#accordionSolution1">
 <div class="accordion-body">
 <p>When you run the <code>python -m oddsong</code> command, Python runs
 the <em>main module as a script</em>.</p>
@@ -3852,7 +3935,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution2" aria-expanded="false" aria-controls="collapseSolution2">
   <h4 class="accordion-header" id="headingSolution2"> Show me the solution </h4>
 </button>
-<div id="collapseSolution2" class="accordion-collapse collapse" data-bs-parent="#accordionSolution2" aria-labelledby="headingSolution2">
+<div id="collapseSolution2" class="accordion-collapse collapse" aria-labelledby="headingSolution2" data-bs-parent="#accordionSolution2">
 <div class="accordion-body">
 <p>When we run our script as before, it will run like normal with no
 change in behaviour.</p>
@@ -3920,7 +4003,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution3" aria-expanded="false" aria-controls="collapseSolution3">
   <h4 class="accordion-header" id="headingSolution3"> Show me the solution </h4>
 </button>
-<div id="collapseSolution3" class="accordion-collapse collapse" data-bs-parent="#accordionSolution3" aria-labelledby="headingSolution3">
+<div id="collapseSolution3" class="accordion-collapse collapse" aria-labelledby="headingSolution3" data-bs-parent="#accordionSolution3">
 <div class="accordion-body">
 <p>The code now looks something like that shown below.</p>
 <div class="codewrapper sourceCode" id="cb25">
@@ -3997,7 +4080,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution4" aria-expanded="false" aria-controls="collapseSolution4">
   <h4 class="accordion-header" id="headingSolution4"> Show me the solution </h4>
 </button>
-<div id="collapseSolution4" class="accordion-collapse collapse" data-bs-parent="#accordionSolution4" aria-labelledby="headingSolution4">
+<div id="collapseSolution4" class="accordion-collapse collapse" aria-labelledby="headingSolution4" data-bs-parent="#accordionSolution4">
 <div class="accordion-body">
 <p>We can achieve this in our example script by adding a
 <code>help</code> string.</p>
@@ -4072,7 +4155,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution5" aria-expanded="false" aria-controls="collapseSolution5">
   <h4 class="accordion-header" id="headingSolution5"> Show me the solution </h4>
 </button>
-<div id="collapseSolution5" class="accordion-collapse collapse" data-bs-parent="#accordionSolution5" aria-labelledby="headingSolution5">
+<div id="collapseSolution5" class="accordion-collapse collapse" aria-labelledby="headingSolution5" data-bs-parent="#accordionSolution5">
 <div class="accordion-body">
 <p>We define the description when creating our argument parser
 object.</p>
diff --git a/cli.html b/cli.html
index e875b05..6c32e54 100644
--- a/cli.html
+++ b/cli.html
@@ -384,7 +384,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Windows">
+<div id="nav-tabpanel-1-Windows" class="tab-pane show active" aria-labelledby="nav-tab-1-Windows" role="tabpanel">
 <p>On Windows operating systems, press the Windows key and type in
 “command”. The start menu will find the “Command Prompt” app. Press
 <kbd>Enter</kbd> or click on the Command Prompt icon to launch the
@@ -404,7 +404,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <p>For more information, see the <a href="https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands" class="external-link">Windows
 Commands</a> page on the Windows Server documentation.</p>
 </div>
-<div id="nav-tabpanel-1-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-Linux">
+<div id="nav-tabpanel-1-Linux" class="tab-pane" aria-labelledby="nav-tab-1-Linux" role="tabpanel">
 <p>On Ubuntu, press <kbd>Ctrl + Alt + T</kbd> to open a terminal.</p>
 <p>You can also open Dash and search for “Terminal”. For detailed
 instructions, please read <a href="https://ubuntu.com/tutorials/command-line-for-beginners#3-opening-a-terminal" class="external-link">Opening
@@ -419,7 +419,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <pre class="sourceCode bash" tabindex="0"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a><span class="ex">bob@myUbuntuPC:~$</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-MacOS">
+<div id="nav-tabpanel-1-MacOS" class="tab-pane" aria-labelledby="nav-tab-1-MacOS" role="tabpanel">
 <p>Please read <a href="https://support.apple.com/en-gb/guide/terminal/apd5265185d-f365-44cb-8b09-71a064a42125/mac" class="external-link">Open
 or quit Terminal on Mac</a> on the <a href="https://support.apple.com/en-gb/guide/terminal/welcome/mac" class="external-link">Terminal
 User Guide</a> for macOS.</p>
@@ -452,7 +452,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Windows">
+<div id="nav-tabpanel-2-Windows" class="tab-pane show active" aria-labelledby="nav-tab-2-Windows" role="tabpanel">
 <p>On Windows, the <a href="https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/dir" class="external-link">dir</a>
 command is used to list the contents of a directory. When you enter this
 command and press <kbd>Enter</kbd></p>
@@ -482,7 +482,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 file was last modified is shown, along with the file size, which is 12
 bytes in this case.</p>
 </div>
-<div id="nav-tabpanel-2-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Linux">
+<div id="nav-tabpanel-2-Linux" class="tab-pane" aria-labelledby="nav-tab-2-Linux" role="tabpanel">
 <p>To show the contents of a directory on a Linux system, we use the <a href="https://manpages.ubuntu.com/manpages/noble/man1/ls.1plan9.html" class="external-link"><code>ls</code>
 command</a> which lists information about the files in the current
 location.</p>
@@ -499,7 +499,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 <pre class="output" tabindex="0"><code><span><span class="va">README.txt</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-MacOS">
+<div id="nav-tabpanel-2-MacOS" class="tab-pane" aria-labelledby="nav-tab-2-MacOS" role="tabpanel">
 <p>The macOS terminal is very similar to the Linux one. To show the
 contents of a directory on a Linux system, we use the <a href="https://support.apple.com/en-gb/guide/terminal/apdb66b5242-0d18-49fc-9c47-a2498b7c91d5/2.14/mac/14.0" class="external-link"><code>ls</code>
 command</a> which lists information about the files in the current
@@ -531,7 +531,7 @@ <h3 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#argumen
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
   <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> What are arguments? </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
 <div class="accordion-body">
 <p>When using shell commands, we use the words <strong>option</strong>,
 <strong>flag</strong>, and <strong>arguments</strong> to describe
@@ -560,7 +560,7 @@ <h3 class="tab-header" id="nav-tab-heading-3-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-3" class="tab-content">
-<div id="nav-tabpanel-3-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-3-Windows">
+<div id="nav-tabpanel-3-Windows" class="tab-pane show active" aria-labelledby="nav-tab-3-Windows" role="tabpanel">
 <p>In the Windows command line, we use the <code>/?</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>dir</code>
@@ -595,7 +595,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 instructions for using it, and a reference to each of the options or
 arguments available.</p>
 </div>
-<div id="nav-tabpanel-3-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-3-Linux">
+<div id="nav-tabpanel-3-Linux" class="tab-pane" aria-labelledby="nav-tab-3-Linux" role="tabpanel">
 <p>In the Linux command line, we use the <code>--help</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>ls</code>
@@ -624,7 +624,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 instructions for using it, and a reference to each of the options or
 arguments available.</p>
 </div>
-<div id="nav-tabpanel-3-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-3-MacOS">
+<div id="nav-tabpanel-3-MacOS" class="tab-pane" aria-labelledby="nav-tab-3-MacOS" role="tabpanel">
 <p>In the macOS command line, we use the <code>--help</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>ls</code>
@@ -673,7 +673,7 @@ <h3 id="getting-started">Getting started<a class="anchor" aria-label="anchor" hr
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler2" aria-expanded="false" aria-controls="collapseSpoiler2">
   <h3 class="accordion-header" id="headingSpoiler2">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Why must our file be named __main__.py? </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
 <div class="accordion-body">
 <p>This is a mechanism that tells Python how we want users to interact
 with our software.</p>
@@ -718,7 +718,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution1" aria-expanded="false" aria-controls="collapseSolution1">
   <h4 class="accordion-header" id="headingSolution1"> Show me the solution </h4>
 </button>
-<div id="collapseSolution1" class="accordion-collapse collapse" data-bs-parent="#accordionSolution1" aria-labelledby="headingSolution1">
+<div id="collapseSolution1" class="accordion-collapse collapse" aria-labelledby="headingSolution1" data-bs-parent="#accordionSolution1">
 <div class="accordion-body">
 <p>When you run the <code>python -m oddsong</code> command, Python runs
 the <em>main module as a script</em>.</p>
@@ -818,7 +818,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution2" aria-expanded="false" aria-controls="collapseSolution2">
   <h4 class="accordion-header" id="headingSolution2"> Show me the solution </h4>
 </button>
-<div id="collapseSolution2" class="accordion-collapse collapse" data-bs-parent="#accordionSolution2" aria-labelledby="headingSolution2">
+<div id="collapseSolution2" class="accordion-collapse collapse" aria-labelledby="headingSolution2" data-bs-parent="#accordionSolution2">
 <div class="accordion-body">
 <p>When we run our script as before, it will run like normal with no
 change in behaviour.</p>
@@ -885,7 +885,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution3" aria-expanded="false" aria-controls="collapseSolution3">
   <h4 class="accordion-header" id="headingSolution3"> Show me the solution </h4>
 </button>
-<div id="collapseSolution3" class="accordion-collapse collapse" data-bs-parent="#accordionSolution3" aria-labelledby="headingSolution3">
+<div id="collapseSolution3" class="accordion-collapse collapse" aria-labelledby="headingSolution3" data-bs-parent="#accordionSolution3">
 <div class="accordion-body">
 <p>The code now looks something like that shown below.</p>
 <div class="codewrapper sourceCode" id="cb25">
@@ -961,7 +961,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution4" aria-expanded="false" aria-controls="collapseSolution4">
   <h4 class="accordion-header" id="headingSolution4"> Show me the solution </h4>
 </button>
-<div id="collapseSolution4" class="accordion-collapse collapse" data-bs-parent="#accordionSolution4" aria-labelledby="headingSolution4">
+<div id="collapseSolution4" class="accordion-collapse collapse" aria-labelledby="headingSolution4" data-bs-parent="#accordionSolution4">
 <div class="accordion-body">
 <p>We can achieve this in our example script by adding a
 <code>help</code> string.</p>
@@ -1035,7 +1035,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution5" aria-expanded="false" aria-controls="collapseSolution5">
   <h4 class="accordion-header" id="headingSolution5"> Show me the solution </h4>
 </button>
-<div id="collapseSolution5" class="accordion-collapse collapse" data-bs-parent="#accordionSolution5" aria-labelledby="headingSolution5">
+<div id="collapseSolution5" class="accordion-collapse collapse" aria-labelledby="headingSolution5" data-bs-parent="#accordionSolution5">
 <div class="accordion-body">
 <p>We define the description when creating our argument parser
 object.</p>
diff --git a/docstrings.html b/docstrings.html
index 5d4ae61..c1ea031 100644
--- a/docstrings.html
+++ b/docstrings.html
@@ -360,7 +360,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Python" class="tab-pane show active" aria-labelledby="nav-tab-1-Python" role="tabpanel">
+<div id="nav-tabpanel-1-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Python">
 <p>In Python, we put a string as the first line of a function (or other
 object.) For example, for a simple Python function that calculates the
 sum of two numbers:</p>
@@ -374,7 +374,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a>    <span class="cf">return</span> x <span class="op">+</span> y</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-R" class="tab-pane" aria-labelledby="nav-tab-1-R" role="tabpanel">
+<div id="nav-tabpanel-1-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-R">
 <p>In R, we use a comment with a single quote <code>#'</code> to specify
 a documentation string for a function.</p>
 <div class="codewrapper sourceCode" id="cb2">
@@ -412,7 +412,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution1" aria-expanded="false" aria-controls="collapseSolution1">
   <h4 class="accordion-header" id="headingSolution1"> Show me the solution </h4>
 </button>
-<div id="collapseSolution1" class="accordion-collapse collapse" data-bs-parent="#accordionSolution1" aria-labelledby="headingSolution1">
+<div id="collapseSolution1" class="accordion-collapse collapse" aria-labelledby="headingSolution1" data-bs-parent="#accordionSolution1">
 <div class="accordion-body">
 <div class="tabs">
 <nav><div id="nav-tab-2" class="nav nav-tabs" role="tablist">
@@ -428,7 +428,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Python" class="tab-pane show active" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <ol style="list-style-type: decimal"><li>Create a new Python script by creating a file called
 <code>oddsong.py</code>;</li>
 <li>Open the file for editing;</li>
@@ -447,7 +447,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb3-8"><a href="#cb3-8" tabindex="-1"></a>    <span class="cf">return</span> <span class="st">"Hirundo atrocaerulea"</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-R" class="tab-pane" aria-labelledby="nav-tab-2-R" role="tabpanel">
+<div id="nav-tabpanel-2-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-R">
 <ol style="list-style-type: decimal"><li>Create a new R script by creating a file called
 <code>oddsong.R</code>;</li>
 <li>Open the file for editing;</li>
@@ -502,7 +502,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution2" aria-expanded="false" aria-controls="collapseSolution2">
   <h4 class="accordion-header" id="headingSolution2"> Show me the solution </h4>
 </button>
-<div id="collapseSolution2" class="accordion-collapse collapse" data-bs-parent="#accordionSolution2" aria-labelledby="headingSolution2">
+<div id="collapseSolution2" class="accordion-collapse collapse" aria-labelledby="headingSolution2" data-bs-parent="#accordionSolution2">
 <div class="accordion-body">
 <p>Let’s view the help text for an in-built <a href="https://docs.python.org/3/library/functions.html#abs" class="external-link">function
 <code>abs()</code></a> that finds the absolute value of a number.</p>
@@ -613,7 +613,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
   <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Using docstrings to create automatic tests </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
 <div class="accordion-body">
 <p>These code examples can be used as automatic tests using the <a href="https://docs.python.org/3/library/doctest.html" class="external-link">doctest</a> module
 which is built into Python.</p>
@@ -645,7 +645,7 @@ <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler2" aria-expanded="false" aria-controls="collapseSpoiler2">
   <h3 class="accordion-header" id="headingSpoiler2">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Docstring conventions </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
 <div class="accordion-body">
 <p>There are several different <strong>standards</strong> for
 documentation strings. A standard is a convention that determines how
diff --git a/index.html b/index.html
index d757fa8..f39643a 100644
--- a/index.html
+++ b/index.html
@@ -385,7 +385,7 @@ <h3 class="accordion-header" id="headingSpoiler1">
   Windows
   </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
 <div class="accordion-body">
 <div class="section level4">
 <h4 id="text-editor">Text editor<a class="anchor" aria-label="anchor" href="#text-editor"></a></h4>
@@ -416,7 +416,7 @@ <h3 class="accordion-header" id="headingSpoiler2">
   MacOS
   </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
 <div class="accordion-body">
 <div class="section level4">
 <h4 id="text-editor-1">Text editor<a class="anchor" aria-label="anchor" href="#text-editor-1"></a></h4>
@@ -445,7 +445,7 @@ <h3 class="accordion-header" id="headingSpoiler3">
   Linux
   </h3>
 </button>
-<div id="collapseSpoiler3" class="accordion-collapse collapse" aria-labelledby="headingSpoiler3" data-bs-parent="#accordionSpoiler3">
+<div id="collapseSpoiler3" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler3" aria-labelledby="headingSpoiler3">
 <div class="accordion-body">
 <div class="section level4">
 <h4 id="text-editor-2">Text editor<a class="anchor" aria-label="anchor" href="#text-editor-2"></a></h4>
diff --git a/instructor/aio.html b/instructor/aio.html
index 502da80..56f24f5 100644
--- a/instructor/aio.html
+++ b/instructor/aio.html
@@ -504,7 +504,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Python" class="tab-pane show active" aria-labelledby="nav-tab-1-Python" role="tabpanel">
+<div id="nav-tabpanel-1-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Python">
 <p>This is some research code that is contained in a Python
 function.</p>
 <div class="codewrapper sourceCode" id="cb1">
@@ -515,7 +515,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a>  <span class="cf">return</span> x <span class="op">*</span> weird_num <span class="op">-</span> angle<span class="op">**</span><span class="dv">3</span> <span class="op">/</span> (weird_num <span class="op">*</span> <span class="dv">2</span>)</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-R" class="tab-pane" aria-labelledby="nav-tab-1-R" role="tabpanel">
+<div id="nav-tabpanel-1-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-R">
 <p>This is some research code that is contained in an R function.</p>
 <div class="codewrapper sourceCode" id="cb2">
 <h3 class="code-label">R<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
@@ -579,7 +579,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-Challenge">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Python" class="tab-pane show active" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <p>This is a function written in the Python programming language that
 calculates a mathematical result, the details of which aren’t relevant.
 This code has plenty of documentation to help us read and understand
@@ -615,7 +615,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb3-26"><a href="#cb3-26" tabindex="-1"></a>  <span class="cf">return</span> sin_value</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-R" class="tab-pane" aria-labelledby="nav-tab-2-R" role="tabpanel">
+<div id="nav-tabpanel-2-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-R">
 <p>This is a function written in the R programming language that
 calculates a mathematical result, the details of which aren’t relevant.
 This code has plenty of documentation to help us read and understand it.
@@ -655,7 +655,7 @@ <h3 class="code-label">R<i aria-hidden="true" data-feather="chevron-left"></i><i
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 </div>
-<div id="nav-tabpanel-2-Python" class="tab-pane" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <p>Read and evaluate this code.</p>
 <ul>
 <li>Can you tell what the purpose of the function is?</li>
@@ -781,7 +781,7 @@ <h3 class="callout-title">Key Points</h3>
 </div>
 </section></section><section id="aio-readmes"><p>Content from <a href="readmes.html">Writing README files</a></p>
 <hr>
-<p>Last updated on 2024-07-22 |
+<p>Last updated on 2024-09-12 |
 
         <a href="https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/edit/main/episodes/readmes.md" class="external-link">Edit this page <i aria-hidden="true" data-feather="edit"></i></a></p>
 <p>Estimated time: <i aria-hidden="true" data-feather="clock"></i> 12 minutes</p>
@@ -892,7 +892,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Windows">
+<div id="nav-tabpanel-1-Windows" class="tab-pane show active" aria-labelledby="nav-tab-1-Windows" role="tabpanel">
 <ol style="list-style-type: decimal">
 <li>Open <a href="https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1" class="external-link">File
 Explorer</a> to browse the file system;</li>
@@ -904,7 +904,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 <li>Double-click on the file to open it for editing.</li>
 </ol>
 </div>
-<div id="nav-tabpanel-1-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-Linux">
+<div id="nav-tabpanel-1-Linux" class="tab-pane" aria-labelledby="nav-tab-1-Linux" role="tabpanel">
 <p>Use the <a href="https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en" class="external-link">File
 Manager</a> to create a new directory called <code>oddsong</code>.
 Inside that folder, create a new text file called
@@ -919,7 +919,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a><span class="fu">nano</span> oddsong/README.txt</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-MacOS">
+<div id="nav-tabpanel-1-MacOS" class="tab-pane" aria-labelledby="nav-tab-1-MacOS" role="tabpanel">
 <p>Use the <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac" class="external-link">Finder</a>
 file manager to create a new directory called <code>oddsong</code>.
 Inside that folder, create a new text file called
@@ -942,35 +942,38 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 </div>
 <p>The essentials contents of a README file are:</p>
 <ul>
-<li>The name of the software. This seems trivial, but a clear title and
-description of a piece of software will be essential for others to
-identify your software and differentiate it from others.</li>
-<li>A brief introduction to your code, including links to relevant
-websites or contact details for the maintainers. - It should be clear
-who the target audience is for the software package.</li>
-<li>Installation instructions or a link to further information published
-elsewhere.</li>
-<li>Usage instructions, ideally including a “quick start” guide with a
-few simple examples to get people up and running with your software
-package.</li>
+<li>The <strong>name of the software</strong>. This seems trivial, but a
+clear title and description of a piece of software will be essential for
+others to identify your software and differentiate it from others.</li>
+<li>A <strong>brief introduction</strong> to your code, including links
+to relevant websites or contact details for the maintainers.</li>
+<li>It should be clear who the <strong>target audience</strong> is for
+the software package.</li>
+<li>
+<strong>Installation instructions</strong> or a link to further
+information published elsewhere.</li>
+<li>
+<strong>Usage instructions</strong>, ideally including a “quick
+start” guide with a few simple examples to get people up and running
+with your software package.</li>
 </ul>
 <p>It can be useful to signpost to other, related useful software tools
 by providing links and explaining how other software is related or
 different to this project when it comes to addressing these kinds of
 research problems.</p>
-<div id="callout1" class="callout">
+<div id="walk-a-mile-in-the-users-shoes" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="walk-a-mile-in-the-users-shoes" class="callout-inner">
+<h3 class="callout-title">Walk a mile in the user’s shoes</h3>
 <div class="callout-content">
-<p>Put yourself in the shoes of a researcher who has encountered your
+<p>Put yourself in the position of a researcher who has encountered your
 software for the first time. Consider, if you had to start from square
-one, how would you like the code to be introduced to you? Remember:
-things that are obvious to you and your colleagues may not be clear to
-others. What assumed knowledge must you explicitly explain to get them
-up to speed?</p>
+one, how would you like the code to be introduced to you?</p>
+<p>Remember: things that are obvious to you and your colleagues may not
+be clear to others. What <strong>assumed knowledge</strong> must you
+explicitly explain to get them up to speed?</p>
 </div>
 </div>
 </div>
@@ -994,7 +997,7 @@ <h3 id="installation-instructions">Installation instructions<a class="anchor" ar
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 <div class="callout-inner">
-<h3 class="callout-title">Challenge</h3>
+<h3 class="callout-title">Discussion</h3>
 <div class="callout-content">
 <p>Consider a research code project you’ve worked on. Discuss the
 technical prerequisites for that software or system. What would someone
@@ -1033,18 +1036,21 @@ <h3 id="user-guide">User guide<a class="anchor" aria-label="anchor" href="#user-
 <p>Many users will benefit from a frequently asked questions (FAQ) or
 troubleshooting notes, which describes common error messages, explains
 why they occur, and the steps to resolve them.</p>
-<div id="callout2" class="callout">
+<div id="writing-style" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="writing-style" class="callout-inner">
+<h3 class="callout-title">Writing style</h3>
 <div class="callout-content">
-<p>The writing style should be concise, jargon-free, clear, and pitched
-at the appropriate level to the intended target audience. All technical
-terms and acronyms should be explained. However, don’t reinvent the
-wheel by defining all the terms used, instead link to a reliable
-external source or journal article.</p>
+<p>The writing style should be concise, jargon-free, consistent, and
+pitched at the appropriate level to the intended target audience. All
+technical terms and acronyms should be explained. However, don’t
+reinvent the wheel by defining all the terms used, instead link to a
+reliable external source or journal article.</p>
+<p>For more information about good writing style, please refer to these
+<a href="https://www.writethedocs.org/guide/writing/style-guides/#traditional-writing-style-guide-resources" class="external-link">style
+guides</a>.</p>
 </div>
 </div>
 </div>
@@ -1056,7 +1062,7 @@ <h3 class="callout-title">Callout</h3>
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 <div class="callout-inner">
-<h3 class="callout-title">Challenge</h3>
+<h3 class="callout-title">Discussion</h3>
 <div class="callout-content">
 <p>Discuss with the group:</p>
 <ul>
@@ -1070,6 +1076,8 @@ <h3 class="callout-title">Challenge</h3>
 </div>
 </div>
 </div>
+<p>Not all READMEs must follow this structure. Always adapt the format
+of your documentation to suit the specific needs of your audience.</p>
 </div>
 </section><section><h2 class="section-heading" id="markdown-format">Markdown format<a class="anchor" aria-label="anchor" href="#markdown-format"></a>
 </h2>
@@ -1077,12 +1085,36 @@ <h3 class="callout-title">Challenge</h3>
 <p>Most people prefer to use a file format that allows you to create
 headers to organise the content into sections or chapters, which is much
 clearer for the reader.</p>
-<p>In this case, a Markdown document may be used. Markdown is a simple
-mark-up language that allows you to format your text using symbols to
-represent headers, bold text, bullet lists, etc. that are displayed to
-the user in an appealing way. The Markdown syntax will be converted into
-appealing visual styles that make your documentation more aesthetically
-pleasing and easier to read.</p>
+<p>In this case, a <a href="https://daringfireball.net/projects/markdown/" class="external-link">Markdown</a>
+document may be used. Markdown is a simple <em>markup language</em> that
+allows you to format your text using symbols to represent headers, bold
+text, bullet lists, etc. that are displayed to the user in an appealing
+way. The Markdown syntax will be converted into appealing visual styles
+that make your documentation more aesthetically pleasing and easier to
+read.</p>
+<div id="accordionSpoiler1" class="accordion spoiler-accordion accordion-flush">
+<div class="accordion-item">
+<button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
+  <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> What is a markup language? </h3>
+</button>
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
+<div class="accordion-body">
+<p>A <a href="https://en.wikipedia.org/wiki/Markup_language" class="external-link">markup
+language</a> is a system of special characters that are used to
+<em>decorate</em> or <em>format</em> pieces of <em>plain text</em>. The
+syntax normally consists of symbols or <em>tags</em> that are used to
+<em>encode</em> text, which means <em>implying meaning</em> to make it
+more information-rich. It can be used to structure a documented into
+sections to provide logical organisation so that it’s easier to
+navigate.</p>
+<p>Typically, a markup language is edited in a similar way to a computer
+programming language, and is <strong>rendered</strong> into a document
+with various rich text formatting such as headers, bold face fonts,
+etc.</p>
+</div>
+</div>
+</div>
+</div>
 <div id="challenge2" class="callout challenge">
 <div class="callout-square">
 <i class="callout-icon" data-feather="zap"></i>
@@ -1123,7 +1155,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Windows">
+<div id="nav-tabpanel-2-Windows" class="tab-pane show active" aria-labelledby="nav-tab-2-Windows" role="tabpanel">
 <p>Use <a href="https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1" class="external-link">File
 Explorer</a> to <a href="https://support.microsoft.com/en-gb/office/rename-a-file-baea7aab-760b-4ee0-af58-06e940d505a4" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -1133,7 +1165,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 <li>Type <code>README.md</code>.</li>
 </ol>
 </div>
-<div id="nav-tabpanel-2-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Linux">
+<div id="nav-tabpanel-2-Linux" class="tab-pane" aria-labelledby="nav-tab-2-Linux" role="tabpanel">
 <p>Use the <a href="https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en" class="external-link">File
 Manager</a> to <a href="https://help.ubuntu.com/stable/ubuntu-help/files-rename.html.en" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -1144,7 +1176,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <pre class="sourceCode bash" tabindex="0"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="fu">mv</span> README.txt README.md</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-MacOS">
+<div id="nav-tabpanel-2-MacOS" class="tab-pane" aria-labelledby="nav-tab-2-MacOS" role="tabpanel">
 <p>Use the <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac" class="external-link">Finder</a>
 to <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp1144/mac" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -1309,6 +1341,50 @@ <h3 id="text-formatting">Text formatting<a class="anchor" aria-label="anchor" hr
 </tr>
 </tbody>
 </table>
+<p>These may be used to add emphasis to parts of the text or highligh
+key words and phrases. Using text formatting makes your software
+documentation easier to skim-read, so researchers can quickly find the
+part of the text that’s relevant for what they’re working on.</p>
+<div id="challenge4" class="callout challenge">
+<div class="callout-square">
+<i class="callout-icon" data-feather="zap"></i>
+</div>
+<div class="callout-inner">
+<h3 class="callout-title">Challenge</h3>
+<div class="callout-content">
+<p>Identify several <em>key words</em> in your README file. Highlight
+them in using a bold font face.</p>
+</div>
+</div>
+</div>
+<div id="accordionSolution4" class="accordion challenge-accordion accordion-flush">
+<div class="accordion-item">
+<button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution4" aria-expanded="false" aria-controls="collapseSolution4">
+  <h4 class="accordion-header" id="headingSolution4"> Show me the solution </h4>
+</button>
+<div id="collapseSolution4" class="accordion-collapse collapse" aria-labelledby="headingSolution4" data-bs-parent="#accordionSolution4">
+<div class="accordion-body">
+<p>The Markdown syntax for bold font is to wrap the text in two
+asterixes <code>**</code>. This may be applied to single words or to
+phrases.</p>
+<p>For example:</p>
+<div class="codewrapper sourceCode" id="cb8">
+<h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
+</h3>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a>Identify a bird based on the **sound** of its call.</span></code></pre>
+</div>
+<p>Identify a bird based on the <strong>sound</strong> of its call.</p>
+<div class="codewrapper sourceCode" id="cb9">
+<h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
+</h3>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb9-1"><a href="#cb9-1" tabindex="-1"></a>**Identify a bird** based on the _sound of its call_.</span></code></pre>
+</div>
+<p><strong>Identify a bird</strong> based on the <em>sound of its
+call</em>.</p>
+</div>
+</div>
+</div>
+</div>
 </div>
 <div class="section level3">
 <h3 id="block-quotes">Block quotes<a class="anchor" aria-label="anchor" href="#block-quotes"></a>
@@ -1316,10 +1392,10 @@ <h3 id="block-quotes">Block quotes<a class="anchor" aria-label="anchor" href="#b
 <p>We can create a citation with appealing formatting by using the
 blockquote syntax in Markdown, which is similar to the method used in
 email.</p>
-<div class="codewrapper sourceCode" id="cb8">
+<div class="codewrapper sourceCode" id="cb10">
 <h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
 </h3>
-<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a><span class="at">&gt; This text is part of a blockquote.</span></span></code></pre>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb10-1"><a href="#cb10-1" tabindex="-1"></a><span class="at">&gt; This text is part of a blockquote.</span></span></code></pre>
 </div>
 <p>This will be rendered with the following apperearance:</p>
 <blockquote>
@@ -1335,22 +1411,25 @@ <h3 id="code-blocks">Code blocks<a class="anchor" aria-label="anchor" href="#cod
 <p><code></code></p>
 <pre><code><span><span class="va">pi</span> <span class="op">=</span> <span class="fl">3.14</span></span></code></pre>
 <p></p>
-<div id="callout3" class="callout">
+<div id="markdown" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="markdown" class="callout-inner">
+<h3 class="callout-title">Markdown</h3>
 <div class="callout-content">
 <p>You can learn more about writing documents using Markdown at <a href="https://www.markdownguide.org/" class="external-link">Markdown Guide</a>, a reference
 for using this syntax.</p>
 </div>
 </div>
 </div>
-<p>Remember, the README file is a first impression that research users
-will receive for your software. Make them informative and user-friendly
-to enhance the research experience for others and foster
-collaboration.</p>
+<p>Remember, the README file is a <strong>first impression</strong> that
+research users will receive for your software. A README contains a brief
+description of the software, installation instructions, and a usage
+guide. Make them informative and user-friendly to enhance the research
+experience for others and foster collaboration. The writing style should
+be concide, clear, and explain technical terms. Use diagrams and
+screenshots for clarity.</p>
 <div id="keypoints1" class="callout keypoints">
 <div class="callout-square">
 <i class="callout-icon" data-feather="key"></i>
@@ -1363,23 +1442,27 @@ <h3 class="callout-title">Key Points</h3>
 users on installation, usage, and understanding its capabilities.</li>
 <li>Consider the user’s technical background; write clearly and avoid
 jargon.</li>
-<li>A README contains a brief description of the software, installation
-instructions, and a usage guide.</li>
-<li>The writing style should be concide, clear, and explain technical
-terms.</li>
-<li>Use diagrams and screenshots for clarity.</li>
 <li>Markdown is a recommended format for creating headers, bold text,
 bullet points, etc.</li>
 </ul>
 </div>
 </div>
 </div>
+</div>
+</section><section><h2 class="section-heading" id="further-resources">Further resources<a class="anchor" aria-label="anchor" href="#further-resources"></a>
+</h2>
+<hr class="half-width">
+<p>For more information about writing basic software documentation,
+please review the following materials:</p>
+<ul>
+<li>Raphael Pierzina <a href="https://www.writethedocs.org/videos/eu/2017/hi-my-name-is-readme-raphael-pierzina/" class="external-link">Hi,
+my name is README!</a>
+</li>
+</ul>
 <!--
 Place links that you need to refer to multiple times across pages here. Delete
 any links that you are not going to use.
- -->
-</div>
-</section></section><section id="aio-docstrings"><p>Content from <a href="docstrings.html">Documentation strings</a></p>
+ --></section></section><section id="aio-docstrings"><p>Content from <a href="docstrings.html">Documentation strings</a></p>
 <hr>
 <p>Last updated on 2024-09-12 |
 
@@ -1460,7 +1543,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Python" class="tab-pane show active" aria-labelledby="nav-tab-1-Python" role="tabpanel">
+<div id="nav-tabpanel-1-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Python">
 <p>In Python, we put a string as the first line of a function (or other
 object.) For example, for a simple Python function that calculates the
 sum of two numbers:</p>
@@ -1474,7 +1557,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a>    <span class="cf">return</span> x <span class="op">+</span> y</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-R" class="tab-pane" aria-labelledby="nav-tab-1-R" role="tabpanel">
+<div id="nav-tabpanel-1-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-R">
 <p>In R, we use a comment with a single quote <code>#'</code> to specify
 a documentation string for a function.</p>
 <div class="codewrapper sourceCode" id="cb2">
@@ -1512,7 +1595,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution1" aria-expanded="false" aria-controls="collapseSolution1">
   <h4 class="accordion-header" id="headingSolution1"> Show me the solution </h4>
 </button>
-<div id="collapseSolution1" class="accordion-collapse collapse" data-bs-parent="#accordionSolution1" aria-labelledby="headingSolution1">
+<div id="collapseSolution1" class="accordion-collapse collapse" aria-labelledby="headingSolution1" data-bs-parent="#accordionSolution1">
 <div class="accordion-body">
 <div class="tabs">
 <nav><div id="nav-tab-2" class="nav nav-tabs" role="tablist">
@@ -1528,7 +1611,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Python" class="tab-pane show active" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <ol style="list-style-type: decimal">
 <li>Create a new Python script by creating a file called
 <code>oddsong.py</code>;</li>
@@ -1549,7 +1632,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb3-8"><a href="#cb3-8" tabindex="-1"></a>    <span class="cf">return</span> <span class="st">"Hirundo atrocaerulea"</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-R" class="tab-pane" aria-labelledby="nav-tab-2-R" role="tabpanel">
+<div id="nav-tabpanel-2-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-R">
 <ol style="list-style-type: decimal">
 <li>Create a new R script by creating a file called
 <code>oddsong.R</code>;</li>
@@ -1606,7 +1689,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution2" aria-expanded="false" aria-controls="collapseSolution2">
   <h4 class="accordion-header" id="headingSolution2"> Show me the solution </h4>
 </button>
-<div id="collapseSolution2" class="accordion-collapse collapse" data-bs-parent="#accordionSolution2" aria-labelledby="headingSolution2">
+<div id="collapseSolution2" class="accordion-collapse collapse" aria-labelledby="headingSolution2" data-bs-parent="#accordionSolution2">
 <div class="accordion-body">
 <p>Let’s view the help text for an in-built <a href="https://docs.python.org/3/library/functions.html#abs" class="external-link">function
 <code>abs()</code></a> that finds the absolute value of a number.</p>
@@ -1719,7 +1802,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
   <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Using docstrings to create automatic tests </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
 <div class="accordion-body">
 <p>These code examples can be used as automatic tests using the <a href="https://docs.python.org/3/library/doctest.html" class="external-link">doctest</a> module
 which is built into Python.</p>
@@ -1753,7 +1836,7 @@ <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler2" aria-expanded="false" aria-controls="collapseSpoiler2">
   <h3 class="accordion-header" id="headingSpoiler2">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Docstring conventions </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
 <div class="accordion-body">
 <p>There are several different <strong>standards</strong> for
 documentation strings. A standard is a convention that determines how
@@ -3420,7 +3503,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Windows">
+<div id="nav-tabpanel-1-Windows" class="tab-pane show active" aria-labelledby="nav-tab-1-Windows" role="tabpanel">
 <p>On Windows operating systems, press the Windows key and type in
 “command”. The start menu will find the “Command Prompt” app. Press
 <kbd>Enter</kbd> or click on the Command Prompt icon to launch the
@@ -3440,7 +3523,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <p>For more information, see the <a href="https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands" class="external-link">Windows
 Commands</a> page on the Windows Server documentation.</p>
 </div>
-<div id="nav-tabpanel-1-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-Linux">
+<div id="nav-tabpanel-1-Linux" class="tab-pane" aria-labelledby="nav-tab-1-Linux" role="tabpanel">
 <p>On Ubuntu, press <kbd>Ctrl + Alt + T</kbd> to open a terminal.</p>
 <p>You can also open Dash and search for “Terminal”. For detailed
 instructions, please read <a href="https://ubuntu.com/tutorials/command-line-for-beginners#3-opening-a-terminal" class="external-link">Opening
@@ -3455,7 +3538,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <pre class="sourceCode bash" tabindex="0"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a><span class="ex">bob@myUbuntuPC:~$</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-MacOS">
+<div id="nav-tabpanel-1-MacOS" class="tab-pane" aria-labelledby="nav-tab-1-MacOS" role="tabpanel">
 <p>Please read <a href="https://support.apple.com/en-gb/guide/terminal/apd5265185d-f365-44cb-8b09-71a064a42125/mac" class="external-link">Open
 or quit Terminal on Mac</a> on the <a href="https://support.apple.com/en-gb/guide/terminal/welcome/mac" class="external-link">Terminal
 User Guide</a> for macOS.</p>
@@ -3489,7 +3572,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Windows">
+<div id="nav-tabpanel-2-Windows" class="tab-pane show active" aria-labelledby="nav-tab-2-Windows" role="tabpanel">
 <p>On Windows, the <a href="https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/dir" class="external-link">dir</a>
 command is used to list the contents of a directory. When you enter this
 command and press <kbd>Enter</kbd></p>
@@ -3519,7 +3602,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 file was last modified is shown, along with the file size, which is 12
 bytes in this case.</p>
 </div>
-<div id="nav-tabpanel-2-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Linux">
+<div id="nav-tabpanel-2-Linux" class="tab-pane" aria-labelledby="nav-tab-2-Linux" role="tabpanel">
 <p>To show the contents of a directory on a Linux system, we use the <a href="https://manpages.ubuntu.com/manpages/noble/man1/ls.1plan9.html" class="external-link"><code>ls</code>
 command</a> which lists information about the files in the current
 location.</p>
@@ -3536,7 +3619,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 <pre class="output" tabindex="0"><code><span><span class="va">README.txt</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-MacOS">
+<div id="nav-tabpanel-2-MacOS" class="tab-pane" aria-labelledby="nav-tab-2-MacOS" role="tabpanel">
 <p>The macOS terminal is very similar to the Linux one. To show the
 contents of a directory on a Linux system, we use the <a href="https://support.apple.com/en-gb/guide/terminal/apdb66b5242-0d18-49fc-9c47-a2498b7c91d5/2.14/mac/14.0" class="external-link"><code>ls</code>
 command</a> which lists information about the files in the current
@@ -3569,7 +3652,7 @@ <h3 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#argumen
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
   <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> What are arguments? </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
 <div class="accordion-body">
 <p>When using shell commands, we use the words <strong>option</strong>,
 <strong>flag</strong>, and <strong>arguments</strong> to describe
@@ -3598,7 +3681,7 @@ <h3 class="tab-header" id="nav-tab-heading-3-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-3" class="tab-content">
-<div id="nav-tabpanel-3-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-3-Windows">
+<div id="nav-tabpanel-3-Windows" class="tab-pane show active" aria-labelledby="nav-tab-3-Windows" role="tabpanel">
 <p>In the Windows command line, we use the <code>/?</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>dir</code>
@@ -3633,7 +3716,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 instructions for using it, and a reference to each of the options or
 arguments available.</p>
 </div>
-<div id="nav-tabpanel-3-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-3-Linux">
+<div id="nav-tabpanel-3-Linux" class="tab-pane" aria-labelledby="nav-tab-3-Linux" role="tabpanel">
 <p>In the Linux command line, we use the <code>--help</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>ls</code>
@@ -3662,7 +3745,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 instructions for using it, and a reference to each of the options or
 arguments available.</p>
 </div>
-<div id="nav-tabpanel-3-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-3-MacOS">
+<div id="nav-tabpanel-3-MacOS" class="tab-pane" aria-labelledby="nav-tab-3-MacOS" role="tabpanel">
 <p>In the macOS command line, we use the <code>--help</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>ls</code>
@@ -3714,7 +3797,7 @@ <h3 id="getting-started">Getting started<a class="anchor" aria-label="anchor" hr
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler2" aria-expanded="false" aria-controls="collapseSpoiler2">
   <h3 class="accordion-header" id="headingSpoiler2">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Why must our file be named __main__.py? </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
 <div class="accordion-body">
 <p>This is a mechanism that tells Python how we want users to interact
 with our software.</p>
@@ -3759,7 +3842,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution1" aria-expanded="false" aria-controls="collapseSolution1">
   <h4 class="accordion-header" id="headingSolution1"> Show me the solution </h4>
 </button>
-<div id="collapseSolution1" class="accordion-collapse collapse" data-bs-parent="#accordionSolution1" aria-labelledby="headingSolution1">
+<div id="collapseSolution1" class="accordion-collapse collapse" aria-labelledby="headingSolution1" data-bs-parent="#accordionSolution1">
 <div class="accordion-body">
 <p>When you run the <code>python -m oddsong</code> command, Python runs
 the <em>main module as a script</em>.</p>
@@ -3861,7 +3944,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution2" aria-expanded="false" aria-controls="collapseSolution2">
   <h4 class="accordion-header" id="headingSolution2"> Show me the solution </h4>
 </button>
-<div id="collapseSolution2" class="accordion-collapse collapse" data-bs-parent="#accordionSolution2" aria-labelledby="headingSolution2">
+<div id="collapseSolution2" class="accordion-collapse collapse" aria-labelledby="headingSolution2" data-bs-parent="#accordionSolution2">
 <div class="accordion-body">
 <p>When we run our script as before, it will run like normal with no
 change in behaviour.</p>
@@ -3929,7 +4012,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution3" aria-expanded="false" aria-controls="collapseSolution3">
   <h4 class="accordion-header" id="headingSolution3"> Show me the solution </h4>
 </button>
-<div id="collapseSolution3" class="accordion-collapse collapse" data-bs-parent="#accordionSolution3" aria-labelledby="headingSolution3">
+<div id="collapseSolution3" class="accordion-collapse collapse" aria-labelledby="headingSolution3" data-bs-parent="#accordionSolution3">
 <div class="accordion-body">
 <p>The code now looks something like that shown below.</p>
 <div class="codewrapper sourceCode" id="cb25">
@@ -4006,7 +4089,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution4" aria-expanded="false" aria-controls="collapseSolution4">
   <h4 class="accordion-header" id="headingSolution4"> Show me the solution </h4>
 </button>
-<div id="collapseSolution4" class="accordion-collapse collapse" data-bs-parent="#accordionSolution4" aria-labelledby="headingSolution4">
+<div id="collapseSolution4" class="accordion-collapse collapse" aria-labelledby="headingSolution4" data-bs-parent="#accordionSolution4">
 <div class="accordion-body">
 <p>We can achieve this in our example script by adding a
 <code>help</code> string.</p>
@@ -4081,7 +4164,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution5" aria-expanded="false" aria-controls="collapseSolution5">
   <h4 class="accordion-header" id="headingSolution5"> Show me the solution </h4>
 </button>
-<div id="collapseSolution5" class="accordion-collapse collapse" data-bs-parent="#accordionSolution5" aria-labelledby="headingSolution5">
+<div id="collapseSolution5" class="accordion-collapse collapse" aria-labelledby="headingSolution5" data-bs-parent="#accordionSolution5">
 <div class="accordion-body">
 <p>We define the description when creating our argument parser
 object.</p>
diff --git a/instructor/cli.html b/instructor/cli.html
index 601a82f..fe6d6a4 100644
--- a/instructor/cli.html
+++ b/instructor/cli.html
@@ -386,7 +386,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Windows">
+<div id="nav-tabpanel-1-Windows" class="tab-pane show active" aria-labelledby="nav-tab-1-Windows" role="tabpanel">
 <p>On Windows operating systems, press the Windows key and type in
 “command”. The start menu will find the “Command Prompt” app. Press
 <kbd>Enter</kbd> or click on the Command Prompt icon to launch the
@@ -406,7 +406,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <p>For more information, see the <a href="https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands" class="external-link">Windows
 Commands</a> page on the Windows Server documentation.</p>
 </div>
-<div id="nav-tabpanel-1-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-Linux">
+<div id="nav-tabpanel-1-Linux" class="tab-pane" aria-labelledby="nav-tab-1-Linux" role="tabpanel">
 <p>On Ubuntu, press <kbd>Ctrl + Alt + T</kbd> to open a terminal.</p>
 <p>You can also open Dash and search for “Terminal”. For detailed
 instructions, please read <a href="https://ubuntu.com/tutorials/command-line-for-beginners#3-opening-a-terminal" class="external-link">Opening
@@ -421,7 +421,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <pre class="sourceCode bash" tabindex="0"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a><span class="ex">bob@myUbuntuPC:~$</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-MacOS">
+<div id="nav-tabpanel-1-MacOS" class="tab-pane" aria-labelledby="nav-tab-1-MacOS" role="tabpanel">
 <p>Please read <a href="https://support.apple.com/en-gb/guide/terminal/apd5265185d-f365-44cb-8b09-71a064a42125/mac" class="external-link">Open
 or quit Terminal on Mac</a> on the <a href="https://support.apple.com/en-gb/guide/terminal/welcome/mac" class="external-link">Terminal
 User Guide</a> for macOS.</p>
@@ -454,7 +454,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Windows">
+<div id="nav-tabpanel-2-Windows" class="tab-pane show active" aria-labelledby="nav-tab-2-Windows" role="tabpanel">
 <p>On Windows, the <a href="https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/dir" class="external-link">dir</a>
 command is used to list the contents of a directory. When you enter this
 command and press <kbd>Enter</kbd></p>
@@ -484,7 +484,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 file was last modified is shown, along with the file size, which is 12
 bytes in this case.</p>
 </div>
-<div id="nav-tabpanel-2-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Linux">
+<div id="nav-tabpanel-2-Linux" class="tab-pane" aria-labelledby="nav-tab-2-Linux" role="tabpanel">
 <p>To show the contents of a directory on a Linux system, we use the <a href="https://manpages.ubuntu.com/manpages/noble/man1/ls.1plan9.html" class="external-link"><code>ls</code>
 command</a> which lists information about the files in the current
 location.</p>
@@ -501,7 +501,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 <pre class="output" tabindex="0"><code><span><span class="va">README.txt</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-MacOS">
+<div id="nav-tabpanel-2-MacOS" class="tab-pane" aria-labelledby="nav-tab-2-MacOS" role="tabpanel">
 <p>The macOS terminal is very similar to the Linux one. To show the
 contents of a directory on a Linux system, we use the <a href="https://support.apple.com/en-gb/guide/terminal/apdb66b5242-0d18-49fc-9c47-a2498b7c91d5/2.14/mac/14.0" class="external-link"><code>ls</code>
 command</a> which lists information about the files in the current
@@ -533,7 +533,7 @@ <h3 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#argumen
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
   <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> What are arguments? </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
 <div class="accordion-body">
 <p>When using shell commands, we use the words <strong>option</strong>,
 <strong>flag</strong>, and <strong>arguments</strong> to describe
@@ -562,7 +562,7 @@ <h3 class="tab-header" id="nav-tab-heading-3-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-3" class="tab-content">
-<div id="nav-tabpanel-3-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-3-Windows">
+<div id="nav-tabpanel-3-Windows" class="tab-pane show active" aria-labelledby="nav-tab-3-Windows" role="tabpanel">
 <p>In the Windows command line, we use the <code>/?</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>dir</code>
@@ -597,7 +597,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 instructions for using it, and a reference to each of the options or
 arguments available.</p>
 </div>
-<div id="nav-tabpanel-3-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-3-Linux">
+<div id="nav-tabpanel-3-Linux" class="tab-pane" aria-labelledby="nav-tab-3-Linux" role="tabpanel">
 <p>In the Linux command line, we use the <code>--help</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>ls</code>
@@ -626,7 +626,7 @@ <h3 class="code-label">OUTPUT<i aria-hidden="true" data-feather="chevron-left"><
 instructions for using it, and a reference to each of the options or
 arguments available.</p>
 </div>
-<div id="nav-tabpanel-3-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-3-MacOS">
+<div id="nav-tabpanel-3-MacOS" class="tab-pane" aria-labelledby="nav-tab-3-MacOS" role="tabpanel">
 <p>In the macOS command line, we use the <code>--help</code> argument to
 instruct the computer to print the help information that that command.
 To see helpful reference information for using the <code>ls</code>
@@ -675,7 +675,7 @@ <h3 id="getting-started">Getting started<a class="anchor" aria-label="anchor" hr
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler2" aria-expanded="false" aria-controls="collapseSpoiler2">
   <h3 class="accordion-header" id="headingSpoiler2">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Why must our file be named __main__.py? </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
 <div class="accordion-body">
 <p>This is a mechanism that tells Python how we want users to interact
 with our software.</p>
@@ -720,7 +720,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution1" aria-expanded="false" aria-controls="collapseSolution1">
   <h4 class="accordion-header" id="headingSolution1"> Show me the solution </h4>
 </button>
-<div id="collapseSolution1" class="accordion-collapse collapse" data-bs-parent="#accordionSolution1" aria-labelledby="headingSolution1">
+<div id="collapseSolution1" class="accordion-collapse collapse" aria-labelledby="headingSolution1" data-bs-parent="#accordionSolution1">
 <div class="accordion-body">
 <p>When you run the <code>python -m oddsong</code> command, Python runs
 the <em>main module as a script</em>.</p>
@@ -820,7 +820,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution2" aria-expanded="false" aria-controls="collapseSolution2">
   <h4 class="accordion-header" id="headingSolution2"> Show me the solution </h4>
 </button>
-<div id="collapseSolution2" class="accordion-collapse collapse" data-bs-parent="#accordionSolution2" aria-labelledby="headingSolution2">
+<div id="collapseSolution2" class="accordion-collapse collapse" aria-labelledby="headingSolution2" data-bs-parent="#accordionSolution2">
 <div class="accordion-body">
 <p>When we run our script as before, it will run like normal with no
 change in behaviour.</p>
@@ -887,7 +887,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution3" aria-expanded="false" aria-controls="collapseSolution3">
   <h4 class="accordion-header" id="headingSolution3"> Show me the solution </h4>
 </button>
-<div id="collapseSolution3" class="accordion-collapse collapse" data-bs-parent="#accordionSolution3" aria-labelledby="headingSolution3">
+<div id="collapseSolution3" class="accordion-collapse collapse" aria-labelledby="headingSolution3" data-bs-parent="#accordionSolution3">
 <div class="accordion-body">
 <p>The code now looks something like that shown below.</p>
 <div class="codewrapper sourceCode" id="cb25">
@@ -963,7 +963,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution4" aria-expanded="false" aria-controls="collapseSolution4">
   <h4 class="accordion-header" id="headingSolution4"> Show me the solution </h4>
 </button>
-<div id="collapseSolution4" class="accordion-collapse collapse" data-bs-parent="#accordionSolution4" aria-labelledby="headingSolution4">
+<div id="collapseSolution4" class="accordion-collapse collapse" aria-labelledby="headingSolution4" data-bs-parent="#accordionSolution4">
 <div class="accordion-body">
 <p>We can achieve this in our example script by adding a
 <code>help</code> string.</p>
@@ -1037,7 +1037,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution5" aria-expanded="false" aria-controls="collapseSolution5">
   <h4 class="accordion-header" id="headingSolution5"> Show me the solution </h4>
 </button>
-<div id="collapseSolution5" class="accordion-collapse collapse" data-bs-parent="#accordionSolution5" aria-labelledby="headingSolution5">
+<div id="collapseSolution5" class="accordion-collapse collapse" aria-labelledby="headingSolution5" data-bs-parent="#accordionSolution5">
 <div class="accordion-body">
 <p>We define the description when creating our argument parser
 object.</p>
diff --git a/instructor/docstrings.html b/instructor/docstrings.html
index 430791b..39852cb 100644
--- a/instructor/docstrings.html
+++ b/instructor/docstrings.html
@@ -362,7 +362,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Python" class="tab-pane show active" aria-labelledby="nav-tab-1-Python" role="tabpanel">
+<div id="nav-tabpanel-1-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Python">
 <p>In Python, we put a string as the first line of a function (or other
 object.) For example, for a simple Python function that calculates the
 sum of two numbers:</p>
@@ -376,7 +376,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a>    <span class="cf">return</span> x <span class="op">+</span> y</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-R" class="tab-pane" aria-labelledby="nav-tab-1-R" role="tabpanel">
+<div id="nav-tabpanel-1-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-R">
 <p>In R, we use a comment with a single quote <code>#'</code> to specify
 a documentation string for a function.</p>
 <div class="codewrapper sourceCode" id="cb2">
@@ -414,7 +414,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution1" aria-expanded="false" aria-controls="collapseSolution1">
   <h4 class="accordion-header" id="headingSolution1"> Show me the solution </h4>
 </button>
-<div id="collapseSolution1" class="accordion-collapse collapse" data-bs-parent="#accordionSolution1" aria-labelledby="headingSolution1">
+<div id="collapseSolution1" class="accordion-collapse collapse" aria-labelledby="headingSolution1" data-bs-parent="#accordionSolution1">
 <div class="accordion-body">
 <div class="tabs">
 <nav><div id="nav-tab-2" class="nav nav-tabs" role="tablist">
@@ -430,7 +430,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Python" class="tab-pane show active" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <ol style="list-style-type: decimal"><li>Create a new Python script by creating a file called
 <code>oddsong.py</code>;</li>
 <li>Open the file for editing;</li>
@@ -449,7 +449,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb3-8"><a href="#cb3-8" tabindex="-1"></a>    <span class="cf">return</span> <span class="st">"Hirundo atrocaerulea"</span></span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-R" class="tab-pane" aria-labelledby="nav-tab-2-R" role="tabpanel">
+<div id="nav-tabpanel-2-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-R">
 <ol style="list-style-type: decimal"><li>Create a new R script by creating a file called
 <code>oddsong.R</code>;</li>
 <li>Open the file for editing;</li>
@@ -504,7 +504,7 @@ <h3 class="callout-title">Challenge</h3>
 <button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution2" aria-expanded="false" aria-controls="collapseSolution2">
   <h4 class="accordion-header" id="headingSolution2"> Show me the solution </h4>
 </button>
-<div id="collapseSolution2" class="accordion-collapse collapse" data-bs-parent="#accordionSolution2" aria-labelledby="headingSolution2">
+<div id="collapseSolution2" class="accordion-collapse collapse" aria-labelledby="headingSolution2" data-bs-parent="#accordionSolution2">
 <div class="accordion-body">
 <p>Let’s view the help text for an in-built <a href="https://docs.python.org/3/library/functions.html#abs" class="external-link">function
 <code>abs()</code></a> that finds the absolute value of a number.</p>
@@ -615,7 +615,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
   <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Using docstrings to create automatic tests </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
 <div class="accordion-body">
 <p>These code examples can be used as automatic tests using the <a href="https://docs.python.org/3/library/doctest.html" class="external-link">doctest</a> module
 which is built into Python.</p>
@@ -647,7 +647,7 @@ <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i
 <button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler2" aria-expanded="false" aria-controls="collapseSpoiler2">
   <h3 class="accordion-header" id="headingSpoiler2">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> Docstring conventions </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
 <div class="accordion-body">
 <p>There are several different <strong>standards</strong> for
 documentation strings. A standard is a convention that determines how
diff --git a/instructor/index.html b/instructor/index.html
index 02fac0f..a9113d7 100644
--- a/instructor/index.html
+++ b/instructor/index.html
@@ -481,7 +481,7 @@ <h3 class="accordion-header" id="headingSpoiler1">
   Windows
   </h3>
 </button>
-<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
+<div id="collapseSpoiler1" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler1" aria-labelledby="headingSpoiler1">
 <div class="accordion-body">
 <div class="section level4">
 <h4 id="text-editor">Text editor<a class="anchor" aria-label="anchor" href="#text-editor"></a></h4>
@@ -512,7 +512,7 @@ <h3 class="accordion-header" id="headingSpoiler2">
   MacOS
   </h3>
 </button>
-<div id="collapseSpoiler2" class="accordion-collapse collapse" aria-labelledby="headingSpoiler2" data-bs-parent="#accordionSpoiler2">
+<div id="collapseSpoiler2" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler2" aria-labelledby="headingSpoiler2">
 <div class="accordion-body">
 <div class="section level4">
 <h4 id="text-editor-1">Text editor<a class="anchor" aria-label="anchor" href="#text-editor-1"></a></h4>
@@ -541,7 +541,7 @@ <h3 class="accordion-header" id="headingSpoiler3">
   Linux
   </h3>
 </button>
-<div id="collapseSpoiler3" class="accordion-collapse collapse" aria-labelledby="headingSpoiler3" data-bs-parent="#accordionSpoiler3">
+<div id="collapseSpoiler3" class="accordion-collapse collapse" data-bs-parent="#accordionSpoiler3" aria-labelledby="headingSpoiler3">
 <div class="accordion-body">
 <div class="section level4">
 <h4 id="text-editor-2">Text editor<a class="anchor" aria-label="anchor" href="#text-editor-2"></a></h4>
diff --git a/instructor/introduction.html b/instructor/introduction.html
index a2e2df7..6357053 100644
--- a/instructor/introduction.html
+++ b/instructor/introduction.html
@@ -449,7 +449,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Python" class="tab-pane show active" aria-labelledby="nav-tab-1-Python" role="tabpanel">
+<div id="nav-tabpanel-1-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Python">
 <p>This is some research code that is contained in a Python
 function.</p>
 <div class="codewrapper sourceCode" id="cb1">
@@ -460,7 +460,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a>  <span class="cf">return</span> x <span class="op">*</span> weird_num <span class="op">-</span> angle<span class="op">**</span><span class="dv">3</span> <span class="op">/</span> (weird_num <span class="op">*</span> <span class="dv">2</span>)</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-R" class="tab-pane" aria-labelledby="nav-tab-1-R" role="tabpanel">
+<div id="nav-tabpanel-1-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-R">
 <p>This is some research code that is contained in an R function.</p>
 <div class="codewrapper sourceCode" id="cb2">
 <h3 class="code-label">R<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
@@ -521,7 +521,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-Challenge">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Python" class="tab-pane show active" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <p>This is a function written in the Python programming language that
 calculates a mathematical result, the details of which aren’t relevant.
 This code has plenty of documentation to help us read and understand
@@ -557,7 +557,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb3-26"><a href="#cb3-26" tabindex="-1"></a>  <span class="cf">return</span> sin_value</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-R" class="tab-pane" aria-labelledby="nav-tab-2-R" role="tabpanel">
+<div id="nav-tabpanel-2-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-R">
 <p>This is a function written in the R programming language that
 calculates a mathematical result, the details of which aren’t relevant.
 This code has plenty of documentation to help us read and understand it.
@@ -597,7 +597,7 @@ <h3 class="code-label">R<i aria-hidden="true" data-feather="chevron-left"></i><i
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 </div>
-<div id="nav-tabpanel-2-Python" class="tab-pane" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <p>Read and evaluate this code.</p>
 <ul><li>Can you tell what the purpose of the function is?</li>
 <li>What is the meaning of the variables?</li>
diff --git a/instructor/key-points.html b/instructor/key-points.html
index 3610092..8db8128 100644
--- a/instructor/key-points.html
+++ b/instructor/key-points.html
@@ -349,11 +349,6 @@ <h2 class="accordion-header" id="flush-headingTwelve">
 users on installation, usage, and understanding its capabilities.</li>
 <li>Consider the user’s technical background; write clearly and avoid
 jargon.</li>
-<li>A README contains a brief description of the software, installation
-instructions, and a usage guide.</li>
-<li>The writing style should be concide, clear, and explain technical
-terms.</li>
-<li>Use diagrams and screenshots for clarity.</li>
 <li>Markdown is a recommended format for creating headers, bold text,
 bullet points, etc.</li>
 </ul></section><section id="docstrings"><h2 class="section-heading"><a href="docstrings.html">Documentation strings</a></h2>
diff --git a/instructor/readmes.html b/instructor/readmes.html
index 6c9dc25..5e368b5 100644
--- a/instructor/readmes.html
+++ b/instructor/readmes.html
@@ -172,6 +172,7 @@ <h2 class="accordion-header chapters" id="flush-headingEleven">
         <ul><li><a href="#what-is-a-readme-file">What is a README file?</a></li>
 <li><a href="#how-to-write-a-readme">How to write a README</a></li>
 <li><a href="#markdown-format">Markdown format</a></li>
+<li><a href="#further-resources">Further resources</a></li>
         </ul></div><!--/div.accordion-body-->
     </div><!--/div.accordion-collapse-->
 
@@ -281,7 +282,7 @@ <h2 class="accordion-header" id="flush-headingTwelve">
       </div>
       <hr></nav><main id="main-content" class="main-content"><div class="container lesson-content">
         <h1>Writing README files</h1>
-        <p>Last updated on 2024-07-22 |
+        <p>Last updated on 2024-09-12 |
 
         <a href="https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/edit/main/episodes/readmes.md" class="external-link">Edit this page <i aria-hidden="true" data-feather="edit"></i></a></p>
 
@@ -389,7 +390,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Windows">
+<div id="nav-tabpanel-1-Windows" class="tab-pane show active" aria-labelledby="nav-tab-1-Windows" role="tabpanel">
 <ol style="list-style-type: decimal"><li>Open <a href="https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1" class="external-link">File
 Explorer</a> to browse the file system;</li>
 <li>In a folder, right click and select New → Folder;</li>
@@ -399,7 +400,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 <li>Name the file <code>README.txt</code>;</li>
 <li>Double-click on the file to open it for editing.</li>
 </ol></div>
-<div id="nav-tabpanel-1-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-Linux">
+<div id="nav-tabpanel-1-Linux" class="tab-pane" aria-labelledby="nav-tab-1-Linux" role="tabpanel">
 <p>Use the <a href="https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en" class="external-link">File
 Manager</a> to create a new directory called <code>oddsong</code>.
 Inside that folder, create a new text file called
@@ -414,7 +415,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a><span class="fu">nano</span> oddsong/README.txt</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-MacOS">
+<div id="nav-tabpanel-1-MacOS" class="tab-pane" aria-labelledby="nav-tab-1-MacOS" role="tabpanel">
 <p>Use the <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac" class="external-link">Finder</a>
 file manager to create a new directory called <code>oddsong</code>.
 Inside that folder, create a new text file called
@@ -436,34 +437,37 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 </div>
 </div>
 <p>The essentials contents of a README file are:</p>
-<ul><li>The name of the software. This seems trivial, but a clear title and
-description of a piece of software will be essential for others to
-identify your software and differentiate it from others.</li>
-<li>A brief introduction to your code, including links to relevant
-websites or contact details for the maintainers. - It should be clear
-who the target audience is for the software package.</li>
-<li>Installation instructions or a link to further information published
-elsewhere.</li>
-<li>Usage instructions, ideally including a “quick start” guide with a
-few simple examples to get people up and running with your software
-package.</li>
+<ul><li>The <strong>name of the software</strong>. This seems trivial, but a
+clear title and description of a piece of software will be essential for
+others to identify your software and differentiate it from others.</li>
+<li>A <strong>brief introduction</strong> to your code, including links
+to relevant websites or contact details for the maintainers.</li>
+<li>It should be clear who the <strong>target audience</strong> is for
+the software package.</li>
+<li>
+<strong>Installation instructions</strong> or a link to further
+information published elsewhere.</li>
+<li>
+<strong>Usage instructions</strong>, ideally including a “quick
+start” guide with a few simple examples to get people up and running
+with your software package.</li>
 </ul><p>It can be useful to signpost to other, related useful software tools
 by providing links and explaining how other software is related or
 different to this project when it comes to addressing these kinds of
 research problems.</p>
-<div id="callout1" class="callout">
+<div id="walk-a-mile-in-the-users-shoes" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="walk-a-mile-in-the-users-shoes" class="callout-inner">
+<h3 class="callout-title">Walk a mile in the user’s shoes</h3>
 <div class="callout-content">
-<p>Put yourself in the shoes of a researcher who has encountered your
+<p>Put yourself in the position of a researcher who has encountered your
 software for the first time. Consider, if you had to start from square
-one, how would you like the code to be introduced to you? Remember:
-things that are obvious to you and your colleagues may not be clear to
-others. What assumed knowledge must you explicitly explain to get them
-up to speed?</p>
+one, how would you like the code to be introduced to you?</p>
+<p>Remember: things that are obvious to you and your colleagues may not
+be clear to others. What <strong>assumed knowledge</strong> must you
+explicitly explain to get them up to speed?</p>
 </div>
 </div>
 </div>
@@ -486,7 +490,7 @@ <h3 id="installation-instructions">Installation instructions<a class="anchor" ar
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 <div class="callout-inner">
-<h3 class="callout-title">Challenge</h3>
+<h3 class="callout-title">Discussion</h3>
 <div class="callout-content">
 <p>Consider a research code project you’ve worked on. Discuss the
 technical prerequisites for that software or system. What would someone
@@ -522,18 +526,21 @@ <h3 id="user-guide">User guide<a class="anchor" aria-label="anchor" href="#user-
 <p>Many users will benefit from a frequently asked questions (FAQ) or
 troubleshooting notes, which describes common error messages, explains
 why they occur, and the steps to resolve them.</p>
-<div id="callout2" class="callout">
+<div id="writing-style" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="writing-style" class="callout-inner">
+<h3 class="callout-title">Writing style</h3>
 <div class="callout-content">
-<p>The writing style should be concise, jargon-free, clear, and pitched
-at the appropriate level to the intended target audience. All technical
-terms and acronyms should be explained. However, don’t reinvent the
-wheel by defining all the terms used, instead link to a reliable
-external source or journal article.</p>
+<p>The writing style should be concise, jargon-free, consistent, and
+pitched at the appropriate level to the intended target audience. All
+technical terms and acronyms should be explained. However, don’t
+reinvent the wheel by defining all the terms used, instead link to a
+reliable external source or journal article.</p>
+<p>For more information about good writing style, please refer to these
+<a href="https://www.writethedocs.org/guide/writing/style-guides/#traditional-writing-style-guide-resources" class="external-link">style
+guides</a>.</p>
 </div>
 </div>
 </div>
@@ -545,7 +552,7 @@ <h3 class="callout-title">Callout</h3>
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 <div class="callout-inner">
-<h3 class="callout-title">Challenge</h3>
+<h3 class="callout-title">Discussion</h3>
 <div class="callout-content">
 <p>Discuss with the group:</p>
 <ul><li>Reflecting on your past experiences, what software or systems have
@@ -557,17 +564,43 @@ <h3 class="callout-title">Challenge</h3>
 </ul></div>
 </div>
 </div>
+<p>Not all READMEs must follow this structure. Always adapt the format
+of your documentation to suit the specific needs of your audience.</p>
 </div>
 </section><section><h2 class="section-heading" id="markdown-format">Markdown format<a class="anchor" aria-label="anchor" href="#markdown-format"></a></h2>
 <hr class="half-width"><p>Most people prefer to use a file format that allows you to create
 headers to organise the content into sections or chapters, which is much
 clearer for the reader.</p>
-<p>In this case, a Markdown document may be used. Markdown is a simple
-mark-up language that allows you to format your text using symbols to
-represent headers, bold text, bullet lists, etc. that are displayed to
-the user in an appealing way. The Markdown syntax will be converted into
-appealing visual styles that make your documentation more aesthetically
-pleasing and easier to read.</p>
+<p>In this case, a <a href="https://daringfireball.net/projects/markdown/" class="external-link">Markdown</a>
+document may be used. Markdown is a simple <em>markup language</em> that
+allows you to format your text using symbols to represent headers, bold
+text, bullet lists, etc. that are displayed to the user in an appealing
+way. The Markdown syntax will be converted into appealing visual styles
+that make your documentation more aesthetically pleasing and easier to
+read.</p>
+<div id="accordionSpoiler1" class="accordion spoiler-accordion accordion-flush">
+<div class="accordion-item">
+<button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
+  <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> What is a markup language? </h3>
+</button>
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
+<div class="accordion-body">
+<p>A <a href="https://en.wikipedia.org/wiki/Markup_language" class="external-link">markup
+language</a> is a system of special characters that are used to
+<em>decorate</em> or <em>format</em> pieces of <em>plain text</em>. The
+syntax normally consists of symbols or <em>tags</em> that are used to
+<em>encode</em> text, which means <em>implying meaning</em> to make it
+more information-rich. It can be used to structure a documented into
+sections to provide logical organisation so that it’s easier to
+navigate.</p>
+<p>Typically, a markup language is edited in a similar way to a computer
+programming language, and is <strong>rendered</strong> into a document
+with various rich text formatting such as headers, bold face fonts,
+etc.</p>
+</div>
+</div>
+</div>
+</div>
 <div id="challenge2" class="callout challenge">
 <div class="callout-square">
 <i class="callout-icon" data-feather="zap"></i>
@@ -608,7 +641,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Windows">
+<div id="nav-tabpanel-2-Windows" class="tab-pane show active" aria-labelledby="nav-tab-2-Windows" role="tabpanel">
 <p>Use <a href="https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1" class="external-link">File
 Explorer</a> to <a href="https://support.microsoft.com/en-gb/office/rename-a-file-baea7aab-760b-4ee0-af58-06e940d505a4" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -616,7 +649,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 <li>Right-click on <code>README.txt</code> and select “Rename”;</li>
 <li>Type <code>README.md</code>.</li>
 </ol></div>
-<div id="nav-tabpanel-2-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Linux">
+<div id="nav-tabpanel-2-Linux" class="tab-pane" aria-labelledby="nav-tab-2-Linux" role="tabpanel">
 <p>Use the <a href="https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en" class="external-link">File
 Manager</a> to <a href="https://help.ubuntu.com/stable/ubuntu-help/files-rename.html.en" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -627,7 +660,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <pre class="sourceCode bash" tabindex="0"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="fu">mv</span> README.txt README.md</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-MacOS">
+<div id="nav-tabpanel-2-MacOS" class="tab-pane" aria-labelledby="nav-tab-2-MacOS" role="tabpanel">
 <p>Use the <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac" class="external-link">Finder</a>
 to <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp1144/mac" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -769,16 +802,60 @@ <h3 id="text-formatting">Text formatting<a class="anchor" aria-label="anchor" hr
 <td><code>`code block`</code></td>
 </tr><tr class="odd"><td><a href="https://sheffield.ac.uk" class="external-link">Hyperlink</a></td>
 <td><code>[Hyperlink](https://sheffield.ac.uk)</code></td>
-</tr></tbody></table></div>
+</tr></tbody></table><p>These may be used to add emphasis to parts of the text or highligh
+key words and phrases. Using text formatting makes your software
+documentation easier to skim-read, so researchers can quickly find the
+part of the text that’s relevant for what they’re working on.</p>
+<div id="challenge4" class="callout challenge">
+<div class="callout-square">
+<i class="callout-icon" data-feather="zap"></i>
+</div>
+<div class="callout-inner">
+<h3 class="callout-title">Challenge</h3>
+<div class="callout-content">
+<p>Identify several <em>key words</em> in your README file. Highlight
+them in using a bold font face.</p>
+</div>
+</div>
+</div>
+<div id="accordionSolution4" class="accordion challenge-accordion accordion-flush">
+<div class="accordion-item">
+<button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution4" aria-expanded="false" aria-controls="collapseSolution4">
+  <h4 class="accordion-header" id="headingSolution4"> Show me the solution </h4>
+</button>
+<div id="collapseSolution4" class="accordion-collapse collapse" aria-labelledby="headingSolution4" data-bs-parent="#accordionSolution4">
+<div class="accordion-body">
+<p>The Markdown syntax for bold font is to wrap the text in two
+asterixes <code>**</code>. This may be applied to single words or to
+phrases.</p>
+<p>For example:</p>
+<div class="codewrapper sourceCode" id="cb8">
+<h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
+</h3>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a>Identify a bird based on the **sound** of its call.</span></code></pre>
+</div>
+<p>Identify a bird based on the <strong>sound</strong> of its call.</p>
+<div class="codewrapper sourceCode" id="cb9">
+<h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
+</h3>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb9-1"><a href="#cb9-1" tabindex="-1"></a>**Identify a bird** based on the _sound of its call_.</span></code></pre>
+</div>
+<p><strong>Identify a bird</strong> based on the <em>sound of its
+call</em>.</p>
+</div>
+</div>
+</div>
+</div>
+</div>
 <div class="section level3">
 <h3 id="block-quotes">Block quotes<a class="anchor" aria-label="anchor" href="#block-quotes"></a></h3>
 <p>We can create a citation with appealing formatting by using the
 blockquote syntax in Markdown, which is similar to the method used in
 email.</p>
-<div class="codewrapper sourceCode" id="cb8">
+<div class="codewrapper sourceCode" id="cb10">
 <h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
 </h3>
-<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a><span class="at">&gt; This text is part of a blockquote.</span></span></code></pre>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb10-1"><a href="#cb10-1" tabindex="-1"></a><span class="at">&gt; This text is part of a blockquote.</span></span></code></pre>
 </div>
 <p>This will be rendered with the following apperearance:</p>
 <blockquote>
@@ -793,22 +870,25 @@ <h3 id="code-blocks">Code blocks<a class="anchor" aria-label="anchor" href="#cod
 <p><code></code></p>
 <pre><code><span><span class="va">pi</span> <span class="op">=</span> <span class="fl">3.14</span></span></code></pre>
 <p></p>
-<div id="callout3" class="callout">
+<div id="markdown" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="markdown" class="callout-inner">
+<h3 class="callout-title">Markdown</h3>
 <div class="callout-content">
 <p>You can learn more about writing documents using Markdown at <a href="https://www.markdownguide.org/" class="external-link">Markdown Guide</a>, a reference
 for using this syntax.</p>
 </div>
 </div>
 </div>
-<p>Remember, the README file is a first impression that research users
-will receive for your software. Make them informative and user-friendly
-to enhance the research experience for others and foster
-collaboration.</p>
+<p>Remember, the README file is a <strong>first impression</strong> that
+research users will receive for your software. A README contains a brief
+description of the software, installation instructions, and a usage
+guide. Make them informative and user-friendly to enhance the research
+experience for others and foster collaboration. The writing style should
+be concide, clear, and explain technical terms. Use diagrams and
+screenshots for clarity.</p>
 <div id="keypoints1" class="callout keypoints">
 <div class="callout-square">
 <i class="callout-icon" data-feather="key"></i>
@@ -820,22 +900,22 @@ <h3 class="callout-title">Key Points</h3>
 users on installation, usage, and understanding its capabilities.</li>
 <li>Consider the user’s technical background; write clearly and avoid
 jargon.</li>
-<li>A README contains a brief description of the software, installation
-instructions, and a usage guide.</li>
-<li>The writing style should be concide, clear, and explain technical
-terms.</li>
-<li>Use diagrams and screenshots for clarity.</li>
 <li>Markdown is a recommended format for creating headers, bold text,
 bullet points, etc.</li>
 </ul></div>
 </div>
 </div>
-<!--
+</div>
+</section><section><h2 class="section-heading" id="further-resources">Further resources<a class="anchor" aria-label="anchor" href="#further-resources"></a></h2>
+<hr class="half-width"><p>For more information about writing basic software documentation,
+please review the following materials:</p>
+<ul><li>Raphael Pierzina <a href="https://www.writethedocs.org/videos/eu/2017/hi-my-name-is-readme-raphael-pierzina/" class="external-link">Hi,
+my name is README!</a>
+</li>
+</ul><!--
 Place links that you need to refer to multiple times across pages here. Delete
 any links that you are not going to use.
- -->
-</div>
-</section></div> <!-- / div.lesson-content -->
+ --></section></div> <!-- / div.lesson-content -->
     </main><!-- / main#main-content.main-content --><nav class="bottom-pagination mx-md-4" aria-label="Previous and Next Chapter"><div class="d-block d-sm-block d-md-none">
         <a class="chapter-link" href="../instructor/introduction.html"><i aria-hidden="true" class="small-arrow" data-feather="arrow-left"></i>Previous</a>
         <a class="chapter-link float-end" href="../instructor/docstrings.html">Next<i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i></a>
@@ -906,7 +986,7 @@ <h3 class="callout-title">Key Points</h3>
   "url": "https://Joe-Heffer-Shef.github.io/FAIR4RS-Documentation/instructor/readmes.html",
   "identifier": "https://Joe-Heffer-Shef.github.io/FAIR4RS-Documentation/instructor/readmes.html",
   "dateCreated": "2024-05-20",
-  "dateModified": "2024-07-22",
+  "dateModified": "2024-09-12",
   "datePublished": "2024-09-12"
 }
 
diff --git a/introduction.html b/introduction.html
index 4f8fcb0..76966af 100644
--- a/introduction.html
+++ b/introduction.html
@@ -447,7 +447,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-R">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Python" class="tab-pane show active" aria-labelledby="nav-tab-1-Python" role="tabpanel">
+<div id="nav-tabpanel-1-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Python">
 <p>This is some research code that is contained in a Python
 function.</p>
 <div class="codewrapper sourceCode" id="cb1">
@@ -458,7 +458,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a>  <span class="cf">return</span> x <span class="op">*</span> weird_num <span class="op">-</span> angle<span class="op">**</span><span class="dv">3</span> <span class="op">/</span> (weird_num <span class="op">*</span> <span class="dv">2</span>)</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-R" class="tab-pane" aria-labelledby="nav-tab-1-R" role="tabpanel">
+<div id="nav-tabpanel-1-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-R">
 <p>This is some research code that is contained in an R function.</p>
 <div class="codewrapper sourceCode" id="cb2">
 <h3 class="code-label">R<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
@@ -519,7 +519,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-Challenge">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Python" class="tab-pane show active" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <p>This is a function written in the Python programming language that
 calculates a mathematical result, the details of which aren’t relevant.
 This code has plenty of documentation to help us read and understand
@@ -555,7 +555,7 @@ <h3 class="code-label">PYTHON<i aria-hidden="true" data-feather="chevron-left"><
 <span id="cb3-26"><a href="#cb3-26" tabindex="-1"></a>  <span class="cf">return</span> sin_value</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-R" class="tab-pane" aria-labelledby="nav-tab-2-R" role="tabpanel">
+<div id="nav-tabpanel-2-R" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-R">
 <p>This is a function written in the R programming language that
 calculates a mathematical result, the details of which aren’t relevant.
 This code has plenty of documentation to help us read and understand it.
@@ -595,7 +595,7 @@ <h3 class="code-label">R<i aria-hidden="true" data-feather="chevron-left"></i><i
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 </div>
-<div id="nav-tabpanel-2-Python" class="tab-pane" aria-labelledby="nav-tab-2-Python" role="tabpanel">
+<div id="nav-tabpanel-2-Python" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Python">
 <p>Read and evaluate this code.</p>
 <ul><li>Can you tell what the purpose of the function is?</li>
 <li>What is the meaning of the variables?</li>
diff --git a/key-points.html b/key-points.html
index a1e7cab..3df95b5 100644
--- a/key-points.html
+++ b/key-points.html
@@ -347,11 +347,6 @@ <h2 class="accordion-header" id="flush-headingTwelve">
 users on installation, usage, and understanding its capabilities.</li>
 <li>Consider the user’s technical background; write clearly and avoid
 jargon.</li>
-<li>A README contains a brief description of the software, installation
-instructions, and a usage guide.</li>
-<li>The writing style should be concide, clear, and explain technical
-terms.</li>
-<li>Use diagrams and screenshots for clarity.</li>
 <li>Markdown is a recommended format for creating headers, bold text,
 bullet points, etc.</li>
 </ul></section><section id="docstrings"><h2 class="section-heading"><a href="docstrings.html">Documentation strings</a></h2>
diff --git a/md5sum.txt b/md5sum.txt
index 74c0594..335f440 100644
--- a/md5sum.txt
+++ b/md5sum.txt
@@ -6,7 +6,7 @@
 "index.md" "568532bd1e8c470d82e70a56a5130136" "site/built/index.md" "2024-08-14"
 "links.md" "8184cf4149eafbf03ce8da8ff0778c14" "site/built/links.md" "2024-05-20"
 "episodes/introduction.md" "123579b22c95b6dcb57401b057235db5" "site/built/introduction.md" "2024-08-16"
-"episodes/readmes.md" "7f814493f5072a579424de3222583ebb" "site/built/readmes.md" "2024-07-22"
+"episodes/readmes.md" "657a7d37e210b39f93397a5cc291436c" "site/built/readmes.md" "2024-09-12"
 "episodes/docstrings.md" "144c97b797a8bdeafbaf8a9fae4d2099" "site/built/docstrings.md" "2024-09-12"
 "episodes/readable.md" "1f80fef3634faac146f4d6d324a92a3b" "site/built/readable.md" "2024-08-16"
 "episodes/sites.md" "84cbf67bb259144ed1083711614f8f2a" "site/built/sites.md" "2024-09-12"
diff --git a/pkgdown.yml b/pkgdown.yml
index 8e1ea0e..a533998 100644
--- a/pkgdown.yml
+++ b/pkgdown.yml
@@ -2,4 +2,4 @@ pandoc: 3.1.11
 pkgdown: 2.1.0
 pkgdown_sha: ~
 articles: {}
-last_built: 2024-09-12T12:34Z
+last_built: 2024-09-12T13:41Z
diff --git a/readmes.html b/readmes.html
index 985582e..8530523 100644
--- a/readmes.html
+++ b/readmes.html
@@ -172,6 +172,7 @@ <h2 class="accordion-header chapters" id="flush-headingEleven">
         <ul><li><a href="#what-is-a-readme-file">What is a README file?</a></li>
 <li><a href="#how-to-write-a-readme">How to write a README</a></li>
 <li><a href="#markdown-format">Markdown format</a></li>
+<li><a href="#further-resources">Further resources</a></li>
         </ul></div><!--/div.accordion-body-->
     </div><!--/div.accordion-collapse-->
 
@@ -281,7 +282,7 @@ <h2 class="accordion-header" id="flush-headingTwelve">
       </div>
       <hr></nav><main id="main-content" class="main-content"><div class="container lesson-content">
         <h1>Writing README files</h1>
-        <p>Last updated on 2024-07-22 |
+        <p>Last updated on 2024-09-12 |
 
         <a href="https://github.com/Joe-Heffer-Shef/FAIR4RS-Documentation/edit/main/episodes/readmes.md" class="external-link">Edit this page <i aria-hidden="true" data-feather="edit"></i></a></p>
 
@@ -387,7 +388,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-1" class="tab-content">
-<div id="nav-tabpanel-1-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-1-Windows">
+<div id="nav-tabpanel-1-Windows" class="tab-pane show active" aria-labelledby="nav-tab-1-Windows" role="tabpanel">
 <ol style="list-style-type: decimal"><li>Open <a href="https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1" class="external-link">File
 Explorer</a> to browse the file system;</li>
 <li>In a folder, right click and select New → Folder;</li>
@@ -397,7 +398,7 @@ <h3 class="tab-header" id="nav-tab-heading-1-MacOS">
 <li>Name the file <code>README.txt</code>;</li>
 <li>Double-click on the file to open it for editing.</li>
 </ol></div>
-<div id="nav-tabpanel-1-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-Linux">
+<div id="nav-tabpanel-1-Linux" class="tab-pane" aria-labelledby="nav-tab-1-Linux" role="tabpanel">
 <p>Use the <a href="https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en" class="external-link">File
 Manager</a> to create a new directory called <code>oddsong</code>.
 Inside that folder, create a new text file called
@@ -412,7 +413,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a><span class="fu">nano</span> oddsong/README.txt</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-1-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-1-MacOS">
+<div id="nav-tabpanel-1-MacOS" class="tab-pane" aria-labelledby="nav-tab-1-MacOS" role="tabpanel">
 <p>Use the <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac" class="external-link">Finder</a>
 file manager to create a new directory called <code>oddsong</code>.
 Inside that folder, create a new text file called
@@ -434,34 +435,37 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 </div>
 </div>
 <p>The essentials contents of a README file are:</p>
-<ul><li>The name of the software. This seems trivial, but a clear title and
-description of a piece of software will be essential for others to
-identify your software and differentiate it from others.</li>
-<li>A brief introduction to your code, including links to relevant
-websites or contact details for the maintainers. - It should be clear
-who the target audience is for the software package.</li>
-<li>Installation instructions or a link to further information published
-elsewhere.</li>
-<li>Usage instructions, ideally including a “quick start” guide with a
-few simple examples to get people up and running with your software
-package.</li>
+<ul><li>The <strong>name of the software</strong>. This seems trivial, but a
+clear title and description of a piece of software will be essential for
+others to identify your software and differentiate it from others.</li>
+<li>A <strong>brief introduction</strong> to your code, including links
+to relevant websites or contact details for the maintainers.</li>
+<li>It should be clear who the <strong>target audience</strong> is for
+the software package.</li>
+<li>
+<strong>Installation instructions</strong> or a link to further
+information published elsewhere.</li>
+<li>
+<strong>Usage instructions</strong>, ideally including a “quick
+start” guide with a few simple examples to get people up and running
+with your software package.</li>
 </ul><p>It can be useful to signpost to other, related useful software tools
 by providing links and explaining how other software is related or
 different to this project when it comes to addressing these kinds of
 research problems.</p>
-<div id="callout1" class="callout">
+<div id="walk-a-mile-in-the-users-shoes" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="walk-a-mile-in-the-users-shoes" class="callout-inner">
+<h3 class="callout-title">Walk a mile in the user’s shoes</h3>
 <div class="callout-content">
-<p>Put yourself in the shoes of a researcher who has encountered your
+<p>Put yourself in the position of a researcher who has encountered your
 software for the first time. Consider, if you had to start from square
-one, how would you like the code to be introduced to you? Remember:
-things that are obvious to you and your colleagues may not be clear to
-others. What assumed knowledge must you explicitly explain to get them
-up to speed?</p>
+one, how would you like the code to be introduced to you?</p>
+<p>Remember: things that are obvious to you and your colleagues may not
+be clear to others. What <strong>assumed knowledge</strong> must you
+explicitly explain to get them up to speed?</p>
 </div>
 </div>
 </div>
@@ -484,7 +488,7 @@ <h3 id="installation-instructions">Installation instructions<a class="anchor" ar
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 <div class="callout-inner">
-<h3 class="callout-title">Challenge</h3>
+<h3 class="callout-title">Discussion</h3>
 <div class="callout-content">
 <p>Consider a research code project you’ve worked on. Discuss the
 technical prerequisites for that software or system. What would someone
@@ -520,18 +524,21 @@ <h3 id="user-guide">User guide<a class="anchor" aria-label="anchor" href="#user-
 <p>Many users will benefit from a frequently asked questions (FAQ) or
 troubleshooting notes, which describes common error messages, explains
 why they occur, and the steps to resolve them.</p>
-<div id="callout2" class="callout">
+<div id="writing-style" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="writing-style" class="callout-inner">
+<h3 class="callout-title">Writing style</h3>
 <div class="callout-content">
-<p>The writing style should be concise, jargon-free, clear, and pitched
-at the appropriate level to the intended target audience. All technical
-terms and acronyms should be explained. However, don’t reinvent the
-wheel by defining all the terms used, instead link to a reliable
-external source or journal article.</p>
+<p>The writing style should be concise, jargon-free, consistent, and
+pitched at the appropriate level to the intended target audience. All
+technical terms and acronyms should be explained. However, don’t
+reinvent the wheel by defining all the terms used, instead link to a
+reliable external source or journal article.</p>
+<p>For more information about good writing style, please refer to these
+<a href="https://www.writethedocs.org/guide/writing/style-guides/#traditional-writing-style-guide-resources" class="external-link">style
+guides</a>.</p>
 </div>
 </div>
 </div>
@@ -543,7 +550,7 @@ <h3 class="callout-title">Callout</h3>
 <i class="callout-icon" data-feather="message-circle"></i>
 </div>
 <div class="callout-inner">
-<h3 class="callout-title">Challenge</h3>
+<h3 class="callout-title">Discussion</h3>
 <div class="callout-content">
 <p>Discuss with the group:</p>
 <ul><li>Reflecting on your past experiences, what software or systems have
@@ -555,17 +562,43 @@ <h3 class="callout-title">Challenge</h3>
 </ul></div>
 </div>
 </div>
+<p>Not all READMEs must follow this structure. Always adapt the format
+of your documentation to suit the specific needs of your audience.</p>
 </div>
 </section><section><h2 class="section-heading" id="markdown-format">Markdown format<a class="anchor" aria-label="anchor" href="#markdown-format"></a></h2>
 <hr class="half-width"><p>Most people prefer to use a file format that allows you to create
 headers to organise the content into sections or chapters, which is much
 clearer for the reader.</p>
-<p>In this case, a Markdown document may be used. Markdown is a simple
-mark-up language that allows you to format your text using symbols to
-represent headers, bold text, bullet lists, etc. that are displayed to
-the user in an appealing way. The Markdown syntax will be converted into
-appealing visual styles that make your documentation more aesthetically
-pleasing and easier to read.</p>
+<p>In this case, a <a href="https://daringfireball.net/projects/markdown/" class="external-link">Markdown</a>
+document may be used. Markdown is a simple <em>markup language</em> that
+allows you to format your text using symbols to represent headers, bold
+text, bullet lists, etc. that are displayed to the user in an appealing
+way. The Markdown syntax will be converted into appealing visual styles
+that make your documentation more aesthetically pleasing and easier to
+read.</p>
+<div id="accordionSpoiler1" class="accordion spoiler-accordion accordion-flush">
+<div class="accordion-item">
+<button class="accordion-button spoiler-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSpoiler1" aria-expanded="false" aria-controls="collapseSpoiler1">
+  <h3 class="accordion-header" id="headingSpoiler1">  <div class="note-square"><i aria-hidden="true" class="callout-icon" data-feather="eye"></i></div> What is a markup language? </h3>
+</button>
+<div id="collapseSpoiler1" class="accordion-collapse collapse" aria-labelledby="headingSpoiler1" data-bs-parent="#accordionSpoiler1">
+<div class="accordion-body">
+<p>A <a href="https://en.wikipedia.org/wiki/Markup_language" class="external-link">markup
+language</a> is a system of special characters that are used to
+<em>decorate</em> or <em>format</em> pieces of <em>plain text</em>. The
+syntax normally consists of symbols or <em>tags</em> that are used to
+<em>encode</em> text, which means <em>implying meaning</em> to make it
+more information-rich. It can be used to structure a documented into
+sections to provide logical organisation so that it’s easier to
+navigate.</p>
+<p>Typically, a markup language is edited in a similar way to a computer
+programming language, and is <strong>rendered</strong> into a document
+with various rich text formatting such as headers, bold face fonts,
+etc.</p>
+</div>
+</div>
+</div>
+</div>
 <div id="challenge2" class="callout challenge">
 <div class="callout-square">
 <i class="callout-icon" data-feather="zap"></i>
@@ -606,7 +639,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 </button>
 </div>
 </nav><div id="nav-tabContent-2" class="tab-content">
-<div id="nav-tabpanel-2-Windows" class="tab-pane show active" role="tabpanel" aria-labelledby="nav-tab-2-Windows">
+<div id="nav-tabpanel-2-Windows" class="tab-pane show active" aria-labelledby="nav-tab-2-Windows" role="tabpanel">
 <p>Use <a href="https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1" class="external-link">File
 Explorer</a> to <a href="https://support.microsoft.com/en-gb/office/rename-a-file-baea7aab-760b-4ee0-af58-06e940d505a4" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -614,7 +647,7 @@ <h3 class="tab-header" id="nav-tab-heading-2-MacOS">
 <li>Right-click on <code>README.txt</code> and select “Rename”;</li>
 <li>Type <code>README.md</code>.</li>
 </ol></div>
-<div id="nav-tabpanel-2-Linux" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-Linux">
+<div id="nav-tabpanel-2-Linux" class="tab-pane" aria-labelledby="nav-tab-2-Linux" role="tabpanel">
 <p>Use the <a href="https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en" class="external-link">File
 Manager</a> to <a href="https://help.ubuntu.com/stable/ubuntu-help/files-rename.html.en" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -625,7 +658,7 @@ <h3 class="code-label">BASH<i aria-hidden="true" data-feather="chevron-left"></i
 <pre class="sourceCode bash" tabindex="0"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" tabindex="-1"></a><span class="fu">mv</span> README.txt README.md</span></code></pre>
 </div>
 </div>
-<div id="nav-tabpanel-2-MacOS" class="tab-pane" role="tabpanel" aria-labelledby="nav-tab-2-MacOS">
+<div id="nav-tabpanel-2-MacOS" class="tab-pane" aria-labelledby="nav-tab-2-MacOS" role="tabpanel">
 <p>Use the <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac" class="external-link">Finder</a>
 to <a href="https://support.apple.com/en-gb/guide/mac-help/mchlp1144/mac" class="external-link">rename
 the file</a> from <code>README.txt</code> to <code>README.md</code>.</p>
@@ -767,16 +800,60 @@ <h3 id="text-formatting">Text formatting<a class="anchor" aria-label="anchor" hr
 <td><code>`code block`</code></td>
 </tr><tr class="odd"><td><a href="https://sheffield.ac.uk" class="external-link">Hyperlink</a></td>
 <td><code>[Hyperlink](https://sheffield.ac.uk)</code></td>
-</tr></tbody></table></div>
+</tr></tbody></table><p>These may be used to add emphasis to parts of the text or highligh
+key words and phrases. Using text formatting makes your software
+documentation easier to skim-read, so researchers can quickly find the
+part of the text that’s relevant for what they’re working on.</p>
+<div id="challenge4" class="callout challenge">
+<div class="callout-square">
+<i class="callout-icon" data-feather="zap"></i>
+</div>
+<div class="callout-inner">
+<h3 class="callout-title">Challenge</h3>
+<div class="callout-content">
+<p>Identify several <em>key words</em> in your README file. Highlight
+them in using a bold font face.</p>
+</div>
+</div>
+</div>
+<div id="accordionSolution4" class="accordion challenge-accordion accordion-flush">
+<div class="accordion-item">
+<button class="accordion-button solution-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseSolution4" aria-expanded="false" aria-controls="collapseSolution4">
+  <h4 class="accordion-header" id="headingSolution4"> Show me the solution </h4>
+</button>
+<div id="collapseSolution4" class="accordion-collapse collapse" aria-labelledby="headingSolution4" data-bs-parent="#accordionSolution4">
+<div class="accordion-body">
+<p>The Markdown syntax for bold font is to wrap the text in two
+asterixes <code>**</code>. This may be applied to single words or to
+phrases.</p>
+<p>For example:</p>
+<div class="codewrapper sourceCode" id="cb8">
+<h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
+</h3>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a>Identify a bird based on the **sound** of its call.</span></code></pre>
+</div>
+<p>Identify a bird based on the <strong>sound</strong> of its call.</p>
+<div class="codewrapper sourceCode" id="cb9">
+<h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
+</h3>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb9-1"><a href="#cb9-1" tabindex="-1"></a>**Identify a bird** based on the _sound of its call_.</span></code></pre>
+</div>
+<p><strong>Identify a bird</strong> based on the <em>sound of its
+call</em>.</p>
+</div>
+</div>
+</div>
+</div>
+</div>
 <div class="section level3">
 <h3 id="block-quotes">Block quotes<a class="anchor" aria-label="anchor" href="#block-quotes"></a></h3>
 <p>We can create a citation with appealing formatting by using the
 blockquote syntax in Markdown, which is similar to the method used in
 email.</p>
-<div class="codewrapper sourceCode" id="cb8">
+<div class="codewrapper sourceCode" id="cb10">
 <h3 class="code-label">MARKDOWN<i aria-hidden="true" data-feather="chevron-left"></i><i aria-hidden="true" data-feather="chevron-right"></i>
 </h3>
-<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb8-1"><a href="#cb8-1" tabindex="-1"></a><span class="at">&gt; This text is part of a blockquote.</span></span></code></pre>
+<pre class="sourceCode markdown" tabindex="0"><code class="sourceCode markdown"><span id="cb10-1"><a href="#cb10-1" tabindex="-1"></a><span class="at">&gt; This text is part of a blockquote.</span></span></code></pre>
 </div>
 <p>This will be rendered with the following apperearance:</p>
 <blockquote>
@@ -791,22 +868,25 @@ <h3 id="code-blocks">Code blocks<a class="anchor" aria-label="anchor" href="#cod
 <p><code></code></p>
 <pre><code><span><span class="va">pi</span> <span class="op">=</span> <span class="fl">3.14</span></span></code></pre>
 <p></p>
-<div id="callout3" class="callout">
+<div id="markdown" class="callout">
 <div class="callout-square">
 <i class="callout-icon" data-feather="bell"></i>
 </div>
-<div class="callout-inner">
-<h3 class="callout-title">Callout</h3>
+<div id="markdown" class="callout-inner">
+<h3 class="callout-title">Markdown</h3>
 <div class="callout-content">
 <p>You can learn more about writing documents using Markdown at <a href="https://www.markdownguide.org/" class="external-link">Markdown Guide</a>, a reference
 for using this syntax.</p>
 </div>
 </div>
 </div>
-<p>Remember, the README file is a first impression that research users
-will receive for your software. Make them informative and user-friendly
-to enhance the research experience for others and foster
-collaboration.</p>
+<p>Remember, the README file is a <strong>first impression</strong> that
+research users will receive for your software. A README contains a brief
+description of the software, installation instructions, and a usage
+guide. Make them informative and user-friendly to enhance the research
+experience for others and foster collaboration. The writing style should
+be concide, clear, and explain technical terms. Use diagrams and
+screenshots for clarity.</p>
 <div id="keypoints1" class="callout keypoints">
 <div class="callout-square">
 <i class="callout-icon" data-feather="key"></i>
@@ -818,22 +898,22 @@ <h3 class="callout-title">Key Points</h3>
 users on installation, usage, and understanding its capabilities.</li>
 <li>Consider the user’s technical background; write clearly and avoid
 jargon.</li>
-<li>A README contains a brief description of the software, installation
-instructions, and a usage guide.</li>
-<li>The writing style should be concide, clear, and explain technical
-terms.</li>
-<li>Use diagrams and screenshots for clarity.</li>
 <li>Markdown is a recommended format for creating headers, bold text,
 bullet points, etc.</li>
 </ul></div>
 </div>
 </div>
-<!--
+</div>
+</section><section><h2 class="section-heading" id="further-resources">Further resources<a class="anchor" aria-label="anchor" href="#further-resources"></a></h2>
+<hr class="half-width"><p>For more information about writing basic software documentation,
+please review the following materials:</p>
+<ul><li>Raphael Pierzina <a href="https://www.writethedocs.org/videos/eu/2017/hi-my-name-is-readme-raphael-pierzina/" class="external-link">Hi,
+my name is README!</a>
+</li>
+</ul><!--
 Place links that you need to refer to multiple times across pages here. Delete
 any links that you are not going to use.
- -->
-</div>
-</section></div> <!-- / div.lesson-content -->
+ --></section></div> <!-- / div.lesson-content -->
     </main><!-- / main#main-content.main-content --><nav class="bottom-pagination mx-md-4" aria-label="Previous and Next Chapter"><div class="d-block d-sm-block d-md-none">
         <a class="chapter-link" href="introduction.html"><i aria-hidden="true" class="small-arrow" data-feather="arrow-left"></i>Previous</a>
         <a class="chapter-link float-end" href="docstrings.html">Next<i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i></a>
@@ -904,7 +984,7 @@ <h3 class="callout-title">Key Points</h3>
   "url": "https://Joe-Heffer-Shef.github.io/FAIR4RS-Documentation/readmes.html",
   "identifier": "https://Joe-Heffer-Shef.github.io/FAIR4RS-Documentation/readmes.html",
   "dateCreated": "2024-05-20",
-  "dateModified": "2024-07-22",
+  "dateModified": "2024-09-12",
   "datePublished": "2024-09-12"
 }