Text Simplification for "Before We Start: Interacting with R"

[burginam]

In the R Ecology Lesson, under "Before We Start: Interacting with R" I believe the following edit could:

1) better connect the section to the previous text (which introduces vocabulary like commands, code, execute) and, 2) simplify the difference between running commands in the console and writing a script.

I've pasted the text as it currently is first, and then my suggested edit below it.

Text in current form:

There are two main ways of interacting with R: by using the console or by using script files (plain text files that contain your code). The console pane (in RStudio, the bottom left panel) is the place where commands written in the R language can be typed and executed immediately by the computer. It is also where the results will be shown for commands that have been executed. You can type commands directly into the console and press Enter to execute those commands, but they will be forgotten when you close the session. Because we want our code and workflow to be reproducible, it is better to type the commands we want in the script editor, and save the script. This way, there is a complete record of what we did, and anyone (including our future selves!) can easily replicate the results on their computer.

Suggested simplification:

There are two main ways of interacting with R: 1) writing commands directly into the console, or 2) writing commands into a script file (plain text files that contain code). Commands written into the console (in RStudio, the bottom left panel) will be executed immediately after pressing Enter. Results will appear in the console; however, they will not be saved once you close the session. To improve reproducibility, it is preferable to write commands in a script editor and save the script file. (In RStudio, scripts are written and saved in the upper left pane.) Writing scripts creates a savable record of commands and anyone (including our future selves) can easily replicate the results.

[Teebusch]

Hi @burginam , thank you for your suggestion! I agree that this section could be more clear. I have made some additional edits to your version:

There are two main ways of interacting with R:

1. writing commands directly into the console, or
2. writing and executing commands in a script file.

Commands written into the console (in RStudio, the bottom left panel) will be executed immediately after pressing Enter / Return. The results will appear in the console; however, they will not be saved once you close the session.

To improve reproducibility, it is preferable to write and execute commands in script files (i.e., plain text files that contain code). In RStudio, script files are written and saved in the upper left pane. Script files provide a record of the commands we have executed and allow anyone (including our future selves) to understand our workflow and replicate the results.

The next step would be to make a pull request and have it reviewed by some other maintainers.

[sstevens2]

FYI, I'm going to make a PR adding @burginam and @Teebusch's recommendations next week as apart of a demo on how to edit lessons in GitHub for CarpentryCon next week. Including the exact text again below so I can paste easily during the demo.

---

There are two main ways of interacting with R:

1. writing commands directly into the console, or
2. writing and executing commands in a script file.

Commands written into the console (in RStudio, the bottom left pane) will be executed immediately after pressing Enter/ Return. The results will appear in the console; however, they will not be saved once you close the session.

To improve reproducibility, it is preferable to write and execute commands in script files (i.e., plain text files that contain code). In RStudio, script files are written and saved in the upper left pane. Script files provide a record of the commands we have executed and allow anyone (including our future selves) to understand our workflow and replicate the results.

[DrYKIM]

I like the way @burginam summarizes the two ways of interaction in R. My students are accustomed to ways of clear guidance and wait my summary such as in a nutshell.

[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.