Editorial suggestions for lesson text

[dcallen]

In the Episode: “Before we start,” and under the heading “Why Learn R”

• The wording in the sentence “RStudio is currently a very popular way to not only write your R scripts but also to interact with the R software” could be shortened to improve clarity. Suggest changing to “RStudio is a popular way to write R scripts and interact with the R software”

• The sentence “The learning curve might be steeper than with other software, but with R, the results of your analysis do not rely on remembering a succession of pointing and clicking, but instead on a series of written commands, and that’s a good thing!” could be shortened to improve clarity, and starting off the justification for learning R with a negative evaluation of R (“The learning curve might be steeper than with other software”) could be demotivating for novice learners. Suggest changing to: “In R, the results of your analysis rely on a series of written commands, and not on remembering a succession of pointing and clicking. That is a good thing!”

• The sentence “With a stored series of commands (this is your script)” could be rephrased to improve clarity, suggest “With a stored series of commands in an R script”

• The sentence: “Reproducibility is when someone else (including your future self) can obtain the same results from the same dataset when using the same analysis,” suggest using commas instead of parentheses to make verbiage more clear: “Reproducibility is when someone else, including your future self, can obtain ..”

• The sentence: “An increasing number of journals and funding agencies expect analyses to be reproducible, so knowing R will give you an edge with these requirements” could be rephrased to “An increasing number of journals and funding agencies expect analyses to be reproducible, so using R and saving your code as scripts can help you satisfy these requirements” to improve clarity

• The sentence: “The plotting functionalities in R are endless, and allow you to adjust any aspect of your graph to convey most effectively the message from your data” could be rephrased to “The plotting functionalities in R are endless, and allow you to adjust any aspect of your graph to visualize your data most effectively” to improve clarity

In the Episode: “Before we start,” and under the heading “Getting set up”

• When introducing the term “working directory” for the first time in the sentence “It is good practice to keep a set of related data, analyses, and text self-contained in a single folder, called the working directory.” I suggest adding a sentence or two immediately following that defines the term for a novice learner who may be unfamiliar with the term. I realize later on more attention is given to the topic of a working directory, but at this point in the lesson the reader has not yet reached that, and could be confused. Suggestion: “A ‘working directory’ is the directory or folder where you are currently working. For example, you may have created the directory ‘C:\Documents\R-Ecology-Workshop’ for you to save files in for this workshop on your computer with a Windows operating system.” or something similar would help explain what a working directory is for a novice.

• When introducing the term “object” in the sentence “A workspace is your current working environment in R which includes any user-defined object”, suggest defining what an object is an R for the novice learner. For example, adding a sentence like: “R is an object-based programming environment, and whenever we create anything in R (a vector, a dataframe, a function, a model, etc.), we are creating an object.”

[bcinar15]

These are great suggestions from the community to improve the clarity and quality of the lesson about “Why Learn R”

[RichardLZB888]

Carpentries Instructor trainee, first-time GitHub user, getting familiar with this platform and learning how to contribute.

[penggith]

This is a good first issue

[RERoss]

The suggestions about clarifying and defining terms such as "working directory" and "object" are great recommentations for supporting novice learners.

[tobyhodges]

Thanks everyone for contributing to this discussion. The lesson underwent a major update and reorganisation when https://github.com/datacarpentry/R-ecology-lesson/pull/887 was merged. As this issue relates to content in a version of the lesson before that update took place, I will close it. Please open a new issue if you believe that some or all of the changes being discussed here remain relevant to the redesigned lesson, linking to this thread where appropriate.