JOSE review

[kdillmcfarland]

A list of my recommendations as a result of JOSE review (since a lot of small GitHub issues seems silly).

R for Plotting

• Loading and reviewing data: Add a screen shot of the data table import page
• Exercise: Learning more about functions: round(3.1415,3) rounds to 3.142 not 3.141 on my computer (Mac, R 4.1.1)
• Understanding commands: Ordering of topics is a bit jumbled. Suggest completing discussion of commands without parameters and those with 2+ parameters before giving note about # comments
• Exercise: Read in your own data: It is a bit misleading to note "including file path" as it implies there should be more than just this argument in the solution
• Plotting for data exploration: Is there a reason plots are not printed in this section?
• Color vs. Fill: Suggest using a color other than darkolivegreen. It's difficult to see that the outline color changed in the first plot
• Facets: Typo vertical lines and 'gh-pages' at the end?
• Animated plots: animated gif does not render online
• Map plots: Suggest removing pipe usage since students have not been introduced to this yet.
• Bonus topics!: Style error in render with colo

The Unix Shell

• Man and Help: suggest noting that flags are similar to R parameters to link to previous knowledge
• Using the Manual Pages: suggest moving description of using multiple flags from 'Viewing Files' to here since this is used in the exercise
• Working with files and directories: Moving data to a subdirectory is completed at the end of the section in an exercise but the previous text states that the data are already moved before this. Suggest moving the exercise to between the code and figure moves

Intro to Git & GitHub

• Suggest changes the branch name to main instead of master throughout. As new users, students will download the latest git which uses main as the default name.
• Undoing changes: This section uses checkout and revert which are only later explained in the Bonus section. Given time constraints, it is probably best to move this to the Bonus section where these commands can be more fully explained. See also Teach restore and revert #82
• Comment Changes in GitHub: Would be helpful to add a link to more information on commenting or a screenshoot here

R for Data Analysis

• tidyr is not includes the overview learning objectives
• Cleaning up data: Suggest saving the read_csv output to an object earlier in the workflow then performing the subsequent cleaning on that object. This will reduce the repeated printing of the Column specification information
• Get stats fast with summarize(): Potential place to draw connection between pipes and ggplot +
• Joining data frames: cartoon examples not present
• Suggest adding discussion of the summarise() ungrouping output (override with .groups argument)` message

Writing Reports with R Markdown

• What is R Markdown and why use it?: The first examples of Rmd are provided with no context and it might be a little overwhelming for the student to see the full Rmd right off the bat. It's also difficult to see where one image ends and the next starts. Some possible ideas
  • Put an outline around each image and give it a descriptive title
  • Put the two renders side-by-side so we can easily note the differences
  • Don't include the Rmd screenshot since students build that code throughout the section
• Creating a reports directory: potential space to introduce the terminal within RStudio
• Writing Reports with R Markdown, Starting the report: suggest turning the GitHub steps into a numbered list for improved readability
• Writing Reports with R Markdown, Starting the report: Code showing how to calculate nCountries, etc as well as make kable tables is not shown.
• Writing Reports with R Markdown, Starting the report: Would be helpful to show the render with inline results and kable table at the end of this section so that the student can see how these look within the overall document
• Integrating it all together: Paired exercise: Numbering all says (1). It is unclear when students should push to GitHub and switch roles. Either the exercises should be numbered (instead of the individual questions within) or there should be explicit text saying when to switch roles.
• Bonus questions: No solutions provided

Conclusion

• Asking strangers for help: Suggest adding link to help in making minimal examples. I like StackOverflow's guidelines https://stackoverflow.com/help/minimal-reproducible-example

Minor edits

• Minor edits all lessons

[kdillmcfarland]

Minor edits completed in #151