search

hadley / r-pkgs

Building R packages
https://r-pkgs.org
Other
880 stars 630 forks source link

suggestions for Chapter 5: Fundamental development workflows #793

Closed zkamvar closed 2 years ago

zkamvar commented 2 years ago

N.B. I was asked to review Chapters 1-9 by O'Reilly and instructed to leave specific comments here with the understanding of one issue per chapter, ignoring the TODOs:

The advice in this chapter has remained solid for the last decade (from back when it was still a slide deck on Hadley's website) and I stand by that. Only small suggestions:

Use The Available Package

Suggestion: clarify that "available" is a package and that it is a package whose purpose is explicitly to find package names and maybe dedicate a tip box to this package as an example of one that was developed out of a specific need for people to check if a package was indeed available.

Package Creation

https://github.com/hadley/r-pkgs/blob/31eb7c67788cfc14511668d96615c6ad4be6ea66/Workflow101.Rmd#L150

Suggestion: place package.skeleton() disclaimer in a warning/tip box because if left in the prose, it presents itself as crucial information as opposed to an aside that readers may or may not be aware of.

Rstudio projects

https://github.com/hadley/r-pkgs/blob/31eb7c67788cfc14511668d96615c6ad4be6ea66/Workflow101.Rmd#L195-L197

suggested alt text for image: "screenshot of an RStudio window with a semi-transparent black box displaying keyboard shortcuts that covers a majority of the window"

Working directory and filepath discipline

"We strongly recommend that you leave the working directory of your R process set to the top-level of the source package."

I interpreted "leave" here as a synonym of "depart." Rewording this to "We strongly recommend that you set your working directory to the top-level of the source package" might help.

jennybc commented 2 years ago

The package.skeleton() warning was already converted to callout before I processed this issue.