Merge pull request #37 from rostools/docs/minor-text-edits

index.qmd

@@ -14,20 +14,20 @@ knitr::write_bib(
 
 Reproducibility and open scientific practices are increasingly demanded
 of, and needed by, scientists and researchers in our modern research
-environments. As we our tools for generating data become more
-sophisticated and powerful, we also need to start using more
-sophisticated and powerful tools for processing it. Training on how to
-use these tools and build modern data analysis skills is lacking for
-researchers, even though this work is highly time-consuming and
-technical. As a consequence of this unawareness of the need for these
-skills, how *exactly* data is processed is poorly, if at all, described
-in scientific studies. This hidden aspect of research could have major
+environments. As our tools for generating data become more sophisticated
+and powerful, we also need to start using more sophisticated and
+powerful tools for processing it. Training on how to use these tools and
+how to build modern data analysis skills is lacking for researchers,
+even though this work is highly time-consuming and technical. As a
+consequence of an unawareness of the need for these skills, how
+*exactly* data is processed is poorly, if at all, described in
+scientific studies. This hidden aspect of research could have major
 impacts on the reproducibility of studies. Therefore, this course was
 created specifically to start addressing these types of problems.
 
 The course is designed as a series of participatory live-coding lessons,
-where the instructor and learner code together, and is interspersed with
-hands-on exercises and group work using real-world datasets. This
+where the instructor and learners code together, and is interspersed
+with hands-on exercises and group work using real-world datasets. This
 website contains all of the material for the course, from reading
 material to exercises to images. It is structured as a book, with
 "chapters" as lessons, given in order of appearance. We make heavy use
@@ -49,9 +49,9 @@ Want to contribute to this course? Check out the
 [README](https://github.com/rostools/r-cubed-intermediate/blob/main/README.md)
 file as well as the
 [CONTRIBUTING](https://github.com/rostools/r-cubed-intermediate/blob/main/CONTRIBUTING.md)
-file on the GitLab repository for more details. The main way to
+file on the GitHub repository for more details. The main way to
 contribute is by using [GitHub](https://github.com/) and creating a [new
-Issue](https://github.com/rostools/r-cubed-intermediate/issues/new) to
+issue](https://github.com/rostools/r-cubed-intermediate/issues/new) to
 make comments and give feedback for the material.
 
 ## Target audiences

preamble/pre-course.qmd

@@ -156,7 +156,7 @@ Checking Git config settings:
 survey questions**. *Note* that while GitHub is a natural connection to
 using Git, given the limited time available, we will not be going over
 how to use GitHub. If you want to learn about using GitHub, check out
-the
+this
 [session](https://r-cubed-intro.rostools.org/sessions/version-control.html)
 on it in the introduction course.
 
@@ -264,6 +264,9 @@ usethis::with_project(
 )
 ```
 
+Throughout the course, we will use this document as a sandbox to test
+code out and then move the finished code to other files.
+
 ## Download the course data {#sec-download-data}
 
 To best demonstrate the concepts in the course, we ideally should work
@@ -290,8 +293,9 @@ website](https://physionet.org/content/mmash/1.0.0/):
     use personal data, but it *does not prohibit sharing it or making it
     public*! GDPR and Open Data are not in conflict.
 
-> *Note*: Sometimes the PhysioNet website is slow. If that's the case,
-> use [**this alternative link**](resources/mmash-page.html) instead.
+> *Note*: Sometimes the PhysioNet website, where the MMASH data is
+> described, is slow. If that's the case, use [**this alternative
+> link**](resources/mmash-page.html) instead.
 
 After looking over the MMASH website, you need to setup where to store
 the dataset to prepare it for later processing. While in your `LearnR3`
@@ -672,6 +676,16 @@ fs::file_copy(
 )
 ```
 
+Notice that in the file above, we have added comments to help segment
+sections in the code and explain what is happening in the script. In
+general, adding comments to your code helps not only when others read
+the script, but also you in the future, if/when you forget what was done
+or why it was done. It also creates sections in your code that makes it
+easier to get an overview of the code. However, there is a balance here.
+Too many comments can negatively impact readability, so as much as
+possible, write code in a way that explains what the code is doing,
+rather than rely on comments.
+
 You now have the data ready for the course! At this point, please run
 this function in the Console:
 
@@ -767,3 +781,4 @@ withr::with_dir(
   }
 )
 ```
+

preamble/syllabus.qmd

@@ -19,22 +19,23 @@ irreproducible results.
 With this course, we aim to begin addressing this gap. Using a highly
 practical approach that revolves around code-along sessions (instructor
 and learner coding together), hands-on exercises, and group work,
-participants of the course will be able to:
+participants of the course will know:
 
-1.  Learn and demonstrate what an open and reproducible data processing
-    and analysis workflow looks like.
-2.  Learn and apply some fundamental concepts, techniques, and skills
+1.  How to demonstrate what an open and reproducible data processing and
+    analysis workflow looks like.
+2.  How to apply some fundamental concepts, techniques, and skills
     needed for processing and managing data in a reproducible and
     well-documented way.
-3.  Learn where to go to get help and to continue learning modern data
-    science and analysis skills.
+3.  Where to go to get help and to continue learning modern data science
+    and analysis skills.
 
-By the end of the course, participants will: have improved their
-competency in processing and wrangling datasets; have improved their
-proficiency in using the [R](https://www.r-project.org/) statistical
-computing language; know how to write re-usable and well-documented
-code; and know how to make modern and reproducible data analysis
-projects.
+By the end of the course, participants will:
+
+1.  Have improved their competency in processing and wrangling datasets;
+2.  Have improved their proficiency in using the
+    [R](https://www.r-project.org/) statistical computing language;
+3.  Know how to write re-usable and well-documented code;
+4.  Know how to make modern and reproducible data analysis projects.
 
 ## Is this course for you? {#sec-is-it-for-you}
 
@@ -43,7 +44,7 @@ This course is designed in a specific way and is ideal for you if:
 -   You are a researcher, preferably working in the biomedical field
     (ranging from experimental to epidemiological). Specifically, this
     course targets those working on topics in diabetes and metabolism.
--   You currently or will soon do quantitative data analysis.
+-   You currently are or will soon do quantitative data analysis.
 -   You either:
     -   have taken the [introduction to Reproducible Research in R
         course](https://r-cubed-intro.rostools.org/), since this course
@@ -57,10 +58,10 @@ This course is designed in a specific way and is ideal for you if:
 Considering that this is a natural extension of the [introductory
 r-cubed course](https://r-cubed-intro.rostools.org/), this course
 incorporates tools learned during that course, including basic Git usage
-as well as use of RStudio R Projects. If you *do not* have familiarity
-with these tools, you will need to go over the material from the
-introduction course beforehand (more details about pre-course tasks will
-be sent out a couple of weeks before the course).
+as well as the use of RStudio R Projects. If you *do not* have
+familiarity with these tools, you will need to go over the material from
+the introduction course beforehand (more details about pre-course tasks
+will be sent out a couple of weeks before the course).
 
 While having these assumptions help to focus the content of the course,
 if you have an interest in learning R but don't fit any of the above

sessions/dplyr-joins.qmd

@@ -19,6 +19,8 @@ covering.](/images/overview-create-project-data.svg){#fig-overview-create-projec
 
 ## Learning objectives
 
+The learning objectives of this session are:
+
 1.  Learn what regular expressions are and how to use them on character
     data.
 2.  Learn about and apply the various ways data can be joined.