Merge pull request #76 from archaeolauren/lesson_01_style

Episode 01 style

Author: archaeolauren

episodes/01-introduction.md

@@ -58,90 +58,82 @@ Review [the Reproducible Research Discussion](./reproducible-research-discussion
 
 ## Practices for Building Better Research Software
 
-The practices we will cover for building better research software fall into three areas.
+The topics we will cover for building better research software fall into three areas.
 
-### 1. Things you can do with your own computing environment to enhance the software
+### 1. Improving your own computing environment
 
-* Using virtual development environments ensures your software can be developed and run consistently across different systems, making it easier for you and others to run, reuse, and extend your code.
+* **Using virtual development environments** ensures your software works consistently across different systems, making it easier for you and others to run, reuse, and extend your code.
 
-### 2. Things you can do to improve the source code of the software itself
+### 2. Improving the source code
 
-* Organising and structuring your code and project directory keeps your software clean, modular, and reusable, enhancing its readability, extensibility, and reusability.
-* Following coding conventions for your programming language produces consistently formatted code that others find it easy to read, reuse or extend in their own examples and applications.
-* Writing structured documentation strings and comments within your code will make it more understandable to others who wish to use or extend it. 
-* Testing can save time spent on debugging and ensures that your code is correct and does what it is set out to do, giving you and others confidence in your code and the results it produces.
+* **Organising and structuring your code and project directory** keeps your software clean and modular, enhancing its readability, extensibility, and reusability.
+* **Following coding conventions** produces consistently formatted code that others will find easy to work with.
+* **Writing structured documentation**, such as strings and comments, within your code will make it more understandable to others. 
+* **Testing** reduces time spent debugging and ensures that your code does what you mean it to, increasing confidence in your results.
 
-### 3. Things you can do to make the software easier for other people to use
+### 3. Improving resources for collaboration
 
-* Using version control and collaboration platforms like [GitHub](https://github.com), [GitLab](https://gitlab.com), and [CodeBerg](https://codeberg.org/) makes it easier to share code and work on it together.
-* Fostering a community around your software and promoting collaboration helps to grow a user base for your software and contributes to its long-term sustainability.
-* Providing clear and comprehensive documentation, including code comments, API specifications, setup guides, and usage instructions, ensures your software is easy to understand, use, and extend (by you and others).
-* Accompanying your software with clear information about its licensing terms and how it should be cited ensures that others can reuse and adapt your code with confidence and that you receive credit when they do so.
+* **Using version control and collaboration platforms** like [GitHub](https://github.com), [GitLab](https://gitlab.com), and [CodeBerg](https://codeberg.org/) makes it easier to work on code together.
+* **Fostering a community** and promoting collaboration helps grow a user base for your software, contributing to its long-term sustainability.
+* **Providing clear and comprehensive documentation**, including code comments, API specifications, setup guides, and usage instructions, ensures your software is easy to understand, use, and extend.
+* **Clarifying licensing terms** and citation expectations ensures that others can use your code with confidence and that you receive credit when they do so.
 
 :::::::::::::::::: challenge
 
-### Tools and practices you use (5 min)
+### Your Current Approach (5 min)
 
-Individually,
+Individually, reflect on the following, making notes in the shared collaborative document:
 
-- reflect on what practices or tools you are already using in your software development workflow,
-- list some new practices or tools that you would like to start employing or using.
-
-Write your reflections in the shared collaborative document.
+1. What practices or tools you are already using in your software development workflow?
+2. List some new practices or tools you would like to start employing.
 
 ::::::::::::::::::
 
 ## Our Research Software Project
 
-You are going to follow a fairly typical experience of a new researcher (e.g. a PhD student or a postdoc) joining a research group.
-You were emailed some spacewalks data and analysis code bundled in the `spacewalks.zip` archive, written by another group 
-member who worked on similar things but has since left. You need to be able to install and run this code on your 
-machine, check you can understand it and then adapt it to your own project.
+You are going to emulate a fairly typical experience for a new researcher (e.g. PhD student or postdoc) joining a research group.
+Let's say you were emailed some data on astronaut spacewalks, bundled with analysis code in the `spacewalks.zip` archive. The code was written by a group 
+member who has since left. You need to be able to install and run this code on your 
+machine, check you can understand it, and then adapt it to your own project.
 
 As part of the [setup for this course](./installation-instructions.html#spacewalks), you may have downloaded the `spacewalks.zip` archive. 
 If not, you can [download it](https://github.com/carpentries-incubator/better-research-software-r/raw/refs/heads/main/learners/spacewalks.zip) now.
-Save the `spacewalks.zip` archive to your home directory and extract it - you should get a directory called `spacewalks`.
+Save the `spacewalks.zip` archive to your home directory and extract it — you should get a directory called `spacewalks`.
 
 The first thing you may want to do is inspect the content of the code and data you received. We will use RStudio for browsing, 
-inspecting, modifying files and running our code.
+inspecting, and modifying files as well as running our code.
 
 RStudio is a very handy tool for software development and is used by many researchers worldwide. 
-RStudio is an Integrated Development Environment (IDE).
-IDEs are graphical application that provide a comprehensive workspace for writing, editing, testing, and debugging code - all in one place. 
-While RStudio is seemingly the most popular, current IDE for working with R, there are other IDEs you can use (VS code, Positron, etc).
-To open our directory `spacewalks` in RStudio, we first want to make this an R project.
-
-Having our software development project folder as a project in R is helpful for reproduciblity as well.
-We will discover in the next episode the issues with "hard coding" specific filesystem paths into our project and how using R projects will help us to create consistent file path references within our project.
+It is an Integrated Development Environment (IDE), which are graphical applications that provide a comprehensive workspace for writing, editing, testing, and debugging code - all in one place. 
+While RStudio is probably most popular IDE for working with R, there are others you can use (VS code, Positron, etc).
 
 To open our directory `spacewalks` in RStudio, we first want to make this an R project.
-Having our software development project folder as a project in R is helpful for reproduciblity as well.
-We will discover in the next episode the issues with "hard coding" specific filesystem paths into our project and R projects will help us to create consistent file path references within our project.
+In addition to keeping all our files for this project organized for ourselves, using the project feature in R improves reproducibility.
+We will discover in the next episode the issues with "hard coding" specific filesystem paths, and how using R projects allows us to create consistent file path references.
 
-To create a new project – go to **File -> New Project** this will open the new project setup wizard.
-Choose **Existing Directory**, then navigate to where you extracted your spacewalks folder in your home directory using the **Browse...** button and click **Open** once you have selected the `spacewalks` folder.
+To create a new project, open RStudio and go to **File -> New Project**. This will open the new project setup wizard.
+Choose **Existing Directory**, then navigate to and select the `spacewalks` folder in your home directory using the **Browse...** button. Once the `spacewalks` folder is selected, click **Open**.
 Then click **Create Project**. 
-RStudio will then reopen into your project.  
-Note, now it says `spacewalks` in the upper-right hand corner of RStudio since that project is open and the Files pane is showing the files from the `spacewalks` folder.
-When you return to working on this project later, you can click on the `spackewalks.Rproj` file in your file explorer/finder window or you can use the Rproject menu in the upper-right hand side of RStudio to select which projct you would like to work in.
+RStudio will then reopen into your project.
+Note that it now says `spacewalks` in the upper-right hand corner of RStudio (because that is the open project). The files pane should show the files from inside the `spacewalks` folder.
+When you return to work on this project later, you can open the `spacewalks.Rproj` file from your file manager (i.e., Windows' File Explorer or Mac's Finder), or you can open the project from within RStudio using the Rproject menu in the upper-right corner.
 
 Reproducibility note: For reproducible workflows, it’s best to start each session with a clean environment. Best practice is to turn off workspace saving/loading (Tools → Global Options → General: uncheck “Restore .RData…” and set “Save workspace” to “Never”). If you are prompted to save your workspace when closing RStudio, click "No". This ensures your code runs from a fresh start every time and avoids hidden dependencies on objects left over from previous sessions. 
 
 ::: instructor 
 Pause here for some discussion. Are there instances where saving your workspace might be useful? When or why? 
 :::
 
-You may notice that the software project contains:
+Opening the files pane in RStudio, you should see that the software project contains:
 
 1. A JSON file called `data.json` - a snippet of which is shown below - with data on extra-vehicular activities 
-(EVAs, i.e. spacewalks) undertaken by astronauts and cosmonauts from 1965 to 2013 (data provided by NASA via its [Open Data Portal](https://data.nasa.gov/Raw-Data/Extra-vehicular-Activity-EVA-US-and-Russia/9kcy-zwvn/about_data)).
+(aka EVAs or spacewalks) undertaken by astronauts and cosmonauts from 1965 to 2013 (data provided by NASA via its [Open Data Portal](https://data.nasa.gov/Raw-Data/Extra-vehicular-Activity-EVA-US-and-Russia/9kcy-zwvn/about_data)).
 
-   ![JSON data file snippet showing EVA/spacewalk data including EVA ID, country, crew members, vehicle type, date of the spacewalk, duration, and purpose](fig/astronaut-data-json-single-line-snippet.png){alt='JSON data file snippet showing EVA/spacewalk data including EVA ID, country, crew members, vehicle type, date of the spacewalk, duration, and purpose'}
-2. An R script called `my code v2.R` containing some analysis code.
+   ![JSON data file snippet](fig/astronaut-data-json-single-line-snippet.png){alt='JSON data file snippet showing EVA/spacewalk data including EVA ID, country, crew members, vehicle type, date of the spacewalk, duration, and purpose'}
 
-3. `spacewalks.Rproj` the R project for this folder.
+2. An R script called `my code v2.R`, containing some analysis code.
 
-   <!--- screenshot replacement needed ![The first few lines of a Python script](fig/astronaut-analysis-bad-code-screenshot.png){alt='The first few lines of a Python script used as example code for the episode'} -->
+   ![Screenshot of `my code v2.R` file](fig/inherited-code-screenshot.png){alt='First 16 lines of the `my code v2.R` file, open in RStudio'} 
 
    The code in the R script does some common research tasks:
 
@@ -150,24 +142,26 @@ You may notice that the software project contains:
   * Performs some calculations to generate summary statistics about the data
   * Makes a plot to visualise the data
 
-3. A folder called `astronaut-data-analysis-old` - which presumably contains previous versions of the analysis acting as some sort of a backup.
-4. A hidden file `.DS_Store` - Desktop Services Store is a hidden metadata file automatically created by macOS Finder in every folder, storing user-specific view settings like icon positions, window size, and background colors, acting much like Windows' `desktop.ini`.
-This makes us think that the author was using macOS operating system but this file is not part of the project itself.
+3. `spacewalks.Rproj`, the R project file we just created.
+
+4. A folder called `astronaut-data-analysis-old`, which presumably contains previous versions of the analysis, acting as a backup system.
+
+5. A hidden file called .DS_Store. Standing for Desktop Services Store, this is a metadata file automatically created by macOS Finder, storing user-specific view settings like icon positions, window size, and background colors. The Windows equivalent is desktop.ini. This suggests that the author was using macOS operating system, but this file is not part of the project itself.
 
 
 :::::: challenge
 
 ### Assess the software project (10 min)
 
 Individually inspect the code and data.
-Try and see if you can understand what the code is doing and how it is organised.
+Try to understand what the code is doing and how it is organised.
 
-In the shared document, write down anything that you think is not "quite right", not clear, is missing, or could be done better.
+In the shared document, write down anything that you think is "not quite right", unclear, missing, or non-optimized.
 
 ::: hint
 
 Below are some suggested questions to help you assess the code.
-These are not the only criteria on which you could evaluate the code and you may find other aspects to comment on.
+These are not the only criteria on which you could evaluate the code, and you may find other aspects to comment on.
 
 - If these files were emailed to you, or sent on a chat platform, or handed to you on a memory stick, how easy would it be to find them again in 6 months, or 3 years?
 - Can you understand the code? Does it make sense to you?
@@ -194,16 +188,16 @@ This is a (non-exhaustive) list of things that could be fixed/improved with our
 #### File and variable naming
 
 - the data file (`data.json`) and the R script (`my code v2.R`) could have more descriptive names
-- R script (`my code v2.R`) should not contain blank spaces as it may cause problems when running the code from command line
+- R script's name (`my code v2.R`) should not contain blank spaces as it may cause problems when running the code from command line
 - variables (e.g. `t`, `tt`, `ttt`) should have more descriptive and meaningful names
 - version control is embedded in file name (`my code v2.R`) - there are better ways of keeping track of changes to code and its different versions
-- the project contains a hidden file `.DS_Store` which is local and personal config file that should not be shared and does not even make sense other than on macOS
+- the project contains a hidden file `.DS_Store` which is local and personal config file that does not need to be shared and isn't used outside a Mac ecosystem
 
 #### Code organisation and style
 
-- fixing inconsistent use of `=` vs `<-` in the code
+- fix inconsistent use of `=` vs `<-` in the code
 - remove repeated code and use functions instead
-- import statements should be grouped at the top
+- group import statements together at the top
 - commenting and uncommenting code should not be used to direct the flow of execution / type of analysis being done
 - the code lacks comments, documentation and explanations
 - code structure could be improved to be more modular and not one monolithic piece of code - e.g. use functions for reusable units of functionality
@@ -219,15 +213,15 @@ This is a (non-exhaustive) list of things that could be fixed/improved with our
 #### Documentation
 
 - there is no README documentation to orient the user
-- there is no licence information to say how the code can be reused (which then means it cannot be reused at all)
+- there is no license information to say how the code can be reused (which then means it cannot be reused at all)
 - it is not clear what software dependencies the code has
 - there are no installation instructions or instructions on how to run the code
 
 :::
 
 ::::::
 
-As you have seen from the previous exercise - there are quite a few things that can be improved with this code.
+As you have seen from the previous exercise, there are quite a few things that can be improved with this code.
 We will try to make this research software project a "bit better" for future use.