differences for PR #25

md5sum.txt

@@ -6,7 +6,7 @@
 "index.md" "1514b7f406e9c44b52d7b546687754ba" "site/built/index.md" "2024-05-21"
 "links.md" "8184cf4149eafbf03ce8da8ff0778c14" "site/built/links.md" "2024-05-20"
 "episodes/introduction.md" "6f1ab1c6219c8c248d1eeb446cd0c1e7" "site/built/introduction.md" "2024-07-19"
-"episodes/readmes.md" "5e250917907a73660d7a1e0578f240e9" "site/built/readmes.md" "2024-07-19"
+"episodes/readmes.md" "3ab69b7211f64321954591200c9aa91c" "site/built/readmes.md" "2024-07-19"
 "episodes/docstrings.md" "89213caf0bd6a3f36947b129771db564" "site/built/docstrings.md" "2024-06-18"
 "episodes/readable.md" "8467bcd5dec70d96f10947852d89b1f6" "site/built/readable.md" "2024-05-31"
 "episodes/sites.md" "65aa4c45daf0fd4749034d961dd511c6" "site/built/sites.md" "2024-06-10"

readmes.md

@@ -38,12 +38,53 @@ Let's create a new code project. Create a new, empty directory to contain your w
 
 ::::::::::::::::: solution
 
+Follow these general steps to create a README file.
+The specific details for each operating system are detailed below.
+
+1. Create a directory to contain your project. We call this the _root directory_;
+2. In that directory, create a new text file;
+3. Name the file `README.txt`;
+4. Open the file for editing—start writing your documentation!
+
+::: group-tab
+
+### Windows
+
+1. Open [File Explorer](https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1) to browse the file system;
+2. In a folder, right click and select New → Folder;
+3. Name the folder `oddsong`;
+4. Open that new folder, then right click and select New → Text Document;
+5. Name the file `README.txt`;
+6. Double-click on the file to open it for editing.
+
+### Linux
+
+Use the [File Manager](https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en) to create a new directory called `oddsong`. Inside that folder, create a new text file called `README.txt`.
+
+These steps may be achieved using the terminal as follows:
+
+```bash
+mkdir oddsong
+touch oddsong/README.txt
+echo "This is my code" >> my_project/oddsong.txt
+nano oddsong/README.txt
+```
+
+### MacOS
+
+Use the [Finder](https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac) file manager to create a new directory called `oddsong`. Inside that folder, create a new text file called `README.txt`.
+
+These steps may be achieved using the terminal as follows:
+
 ```bash
-mkdir my_project
-touch my_project/README.txt
-echo "This is my code" >> my_project/README.txt
+mkdir oddsong
+touch oddsong/README.txt
+echo "This is my code" >> my_project/oddsong.txt
+nano oddsong/README.txt
 ```
 
+:::
+
 ::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::::::
@@ -57,12 +98,35 @@ The essentials contents of a README file are:
 
 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.
 
+::: callout
+
+Put yourself in the shoes 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?
+
+:::
+
 For research code, it’s often important to explain the context in which the software was written and the theory behind it. For example, many researchers write analysis packages or workflows that are based on previously-published research, statistical methods, or theoretical models for which citations can be provided. By including references to research papers we better help the users to understand the methods that are implemented by our software, which enables its users to properly cite their sources and increases the users’ confidence that you have applied those methods correctly.
 
 ### Installation instructions
 
 Provide instructions for installing your research software. These steps should be laid out in simple, clear language and organised in a step-by-step manner.
 
+::: challenge
+
+Consider a research code project you've worked on.
+Discuss the technical prerequisites for that software or system.
+What would someone need to do, when starting from a blank slate, to recreate that environment?
+
+Think about:
+
+- What hardware and software did you need?
+- What drivers and libraries were required?
+- What software setup, calibration, and configuration is required?
+
+:::
+
 For most research code, the user will need to install the programming language onto their computer, such as R or Python, so it’s useful to link to the download pages and provide a link to the package manager tools that are commonly used in those ecosystems. This might also include listing any prerequisites such as hardware or software that must be installed first, such as device drivers. 
 
 Consider how the installation method might differ for users of other common operating systems, such as Windows, Linux, and Mac OS.
@@ -83,6 +147,50 @@ Most people prefer to use a file format that allows you to create headers to org
 
 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.
 
+::::::::::::::::::::::::::::::::: challenge
+
+Convert your README file to Markdown format to enable more advanced formatting options.
+
+::::::::::::::::: solution
+
+Follow these steps to rename `README.txt` to `README.md`.
+
+::: group-tab
+
+### Windows
+
+Use [File Explorer](https://support.microsoft.com/en-gb/windows/find-and-open-file-explorer-ef370130-1cca-9dc5-e0df-2f7416fe1cb1) to [rename the file](https://support.microsoft.com/en-gb/office/rename-a-file-baea7aab-760b-4ee0-af58-06e940d505a4) from `README.txt` to `README.md`.
+
+1. Open the `oddsong` directory;
+2. Right-click on `README.txt` and select "Rename";
+3. Type `README.md`.
+
+### Linux
+
+Use the [File Manager](https://help.ubuntu.com/stable/ubuntu-help/files-browse.html.en) to [rename the file](https://help.ubuntu.com/stable/ubuntu-help/files-rename.html.en) from `README.txt` to `README.md`.
+
+This step may be achieved using the terminal as follows:
+
+```bash
+mv README.txt README.md
+```
+
+### MacOS
+
+Use the [Finder](https://support.apple.com/en-gb/guide/mac-help/mchlp2605/mac) to [rename the file](https://support.apple.com/en-gb/guide/mac-help/mchlp1144/mac) from `README.txt` to `README.md`.
+
+This step may be achieved using the terminal as follows:
+
+```bash
+mv README.txt README.md
+```
+
+:::
+
+::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::::::
+
 An example README file in Markdown format is shown below, in a file called `README.md` where .md is the file extension for Markdown files.
 
 ### Section headers