add intro text

episodes/introduction.md

@@ -50,7 +50,7 @@ Here are some examples of some code to perform some geometry. The first example
 
 Here's an example of some code that does... something. It's not clear what this code is for or why it was written.
 
-::: tab
+::: group-tab
 
 ### Python
 
@@ -85,6 +85,10 @@ Maybe the code works, maybe it doesn't (would you trust it?) but it could be mad
 
 Now let's look at an example of best practices in documenting research software.
 
+::: group-tab
+
+### Python
+
 ```python
 import math
 
@@ -112,9 +116,40 @@ def calculate_sine(angle: float) -> float:
     sin_value += sign * (angle ** (2 * i)) / factorial
 
   return sin_value
+```
+
+### R
+
+```R
+# Function to calculate sine using Taylor series approximation
+calculate_sine <- function(angle) {
+  """
+  This function calculates the sine of an angle using the first four terms of the Taylor series.
 
+  Args:
+      angle (numeric): The angle in radians.
+
+  Returns:
+      numeric: The sine of the angle (sin(angle)).
+  """
+
+  sin_value <- angle
+
+  # Loop for the first four terms
+  for (i in 1:4) {
+    factorial <- factorial(2 * i)
+    sign <- (-1)^(i %% 2)  # Alternate signs with modulo (%)
+
+    # Add terms for sine
+    sin_value <- sin_value + sign * (angle^(2 * i)) / factorial
+  }
+
+  return(sin_value)
+}
 ```
 
+:::
+
 This time, the function name is a verb that describes what the code will attempt to do. The description of the function is also written out clearly in a note for the user. There are comment lines (starting with `#`) that explain the mathematicalal method used. Each variable has a descriptive, human-readable name, making the code more intuitive to read. An existing library is used to calculate the factorial, which means we can look up the usage for the `factorial()` function elsewhere.
 
 This approach means that our code is much easier to interpret, maintain, and make changes to in the future.

index.md

@@ -4,10 +4,19 @@ site: sandpaper::sandpaper_site
 
 ## Course description
 
-This course will introduce you to the different ways we can provide guidance to future users and maintainers of our code. These coding best practices range from the very simple, such as leaving a few handy notes, to the complex, generating a reference website that includes tutorials and a detailed reference. The right approach for your projects will probably be a blend of these, and depends on the context and your audience.
+Software documentation helps you and others to use your software successfully in the future and to read your code ensuring that its value is sustained. This course introduces the different ways to provide other researchers with useful documentation for your software.
+
+Research outputs often depend upon the code used to generate them. There are many advantages to making your code more readable. All kinds of research software, whether it’s code for data processing, analysis, and simulations, can be made more reproducible by providing clear context and instructions for using it.
+
+Well-documented software is easier to maintain and has greater sustainability, which means it can continue to be used and modified for a longer period of time, despite changes in technology. If software is more reusable then it encourages others to use it for their research, increasing the number of citations of that software and its overall research impact.
+
 
 ## Course overview
 
+This module is part of the "Coding best practices" section of the FAIR4RS training course.
+
+This course will introduce you to the different ways we can provide guidance to future users and maintainers of our code. These coding best practices range from the very simple, such as leaving a few handy notes, to the complex, generating a reference website that includes tutorials and a detailed reference. The right approach for your projects will probably be a blend of these, and depends on the context and your audience.
+
 This course introduces the different ways to provide other researchers with useful documentation for your software.
 
 - Writing informative README files
@@ -23,4 +32,27 @@ This course introduces the different ways to provide other researchers with usef
 
 There is information about publishing a software package and providing metadata and citation details in Modules 6 and 7 of this course.
 
+## Related modules
+
+For more information about describing and sharing your software, please see the following modules:
+
+- 6. Packaging 
+- 7a. Software repos, DOIs, metadata, citation
+- 7b. Publishing a software paper
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+### Learning outcomes
+
+After completing this course, participants should be able to:
+
+- Write clear and concise software documentation that provides essential information to future users and maintainers;
+- Understand how to make their code more readable, clean, and well-structured;
+- Write clear installation instructions;
+- Write effective comments and doc-strings to explain the purpose of code;
+- Automatically generate documentation websites from their code;
+- Create user-friendly command-line interfaces (CLIs) with clear descriptions of commands and options, along with help messages for individual parameters.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
 [workbench]: https://carpentries.github.io/sandpaper-docs

learners/setup.md

@@ -10,7 +10,7 @@ Please use the tool that you prefer.
 [Python](https://python.org) is a popular language for research computing, and great for general-purpose
 programming as well. We will be using some of the inbuilt functionality of Python 3.
 
-[R](https://cran.rstudio.com/) is a statistical language that is designed for data exploration, visualization,
+The [R programming language](https://cran.rstudio.com/) is a statistical package that is designed for data exploration, visualization,
 and data analysis. To interact with R, the most popular tool is
 [RStudio Desktop](https://posit.co/download/rstudio-desktop/).
 

profiles/learner-profiles.md

@@ -1,5 +1,20 @@
 ---
-title: FIXME
+title: Target audience
 ---
 
-This is a placeholder file. Please add content here. 
+## Target audience
+
+This course is aimed at researchers, including postgraduate research students, who write software (whether a few scripts or something more substantial) as part of their research and who want to follow best practices to make their code and data more reproducible.
+
+This course is intended for researchers who use either of the programming languages Python or R, but no expert knowledge of these is required.
+
+## Prerequisites
+
+Prerequisites
+This module assumes no prior knowledge of software documentation. However, some familiarity with the fundamental concepts of programming languages is necessary. Some of these concepts include:
+
+- Basic **syntax**;
+- Using **functions** for procedural programming;
+- Storing data in **variables**.
+
+Most of the content is relevant to any programming language, but the practical examples will use Python and R. For the sections on generating documentation pages, a basic knowledge of version control using Git and GitHub will be advantageous.