feedback on current state of tutorial - Malika's version

[MalikaIhle]

https://lmu-osc.github.io/introduction-to-renv/comp_reproducible.html

• [x] I think I would start directly at what we need to make a project reproducible and say: In this tutorial, we focus on the practical aspects of making sure that the code we write can be run on other machines, by other people, and in the future. In other words, we want to make sure that our code is portable and future-proof by ensuring the software originally used in creating our code is the same software used by others. Let’s look at this in more detail.
• [x] typo: Keeping tracking line 79
• [x] typo: 'time time' line 102

https://lmu-osc.github.io/introduction-to-renv/technical_definitions.html

• [x] typos: line 30 'extnesions'

https://lmu-osc.github.io/introduction-to-renv/dependencies_in_r.html

• [x] typo: line 16 The goal of package managers in R then is to ensure -> cut 'then'?
• [x] (currently at version 1.0.7). -> make this future proof by adding a date or cutting?
• [x] typo line 106 'Posit Package Mangaer'
• [x] I think I'm ok with the order of packrat, groundhogr, renv as it is currently written

https://lmu-osc.github.io/introduction-to-renv/renv_getting_started.html

• [x] 'Check Status of Project ''The project should be in a consistent state' -> sounds like I need to make sure of something with the verb 'should', but I'm not sure what I;m supposed to do if inconsistent, or to make sure to keep consistent.
• [x] 'we strongly recommend reading the details of Understanding {renv} first.' -> seems like Understanding {renv} could be another page than starting_details, the next page. I think starting details doens't mean much to me, perhaps this page could be renamed 'Understanding {renv}' then this sentence is consistent, and when looking at the navigation on the left it would also make sense to me so far. Alternatively I would revise the sentence to point to the starting details page (in the visible text)
• [x] 'And as noted, the directory structure should look similar to the one below, particularly the presence of the renv directory and the renv.lock file. For reference: the function used in the following example, dir_tree(), is from the {fs} package and is used to display the directory structure of the project. That is, it will list the files and directories in the directory where you are currently working.' -> I got confused for a second here: I would remove 'and as noted' because I thought I missed something but actually not. I would put in italic the 'for reference ....' as it is a side note, I don't need to know this package or function for this tutorial. you're just telling people info on how you generated the graph but what I need to understand as a user is only where this files are, correct?
• [x] 'To get a visual representation of this, consider the following example displaying the recursive dependency tree for the {dplyr} package.' -> now you use another package to plot the tree of dependency but don't mention it in text?
• [x] typo: the discussion about dependencies so far has implied that that another package is -> 'that that'
• [x] typo: 'Packages not already installed in the package' ->? ?? in the project library?

https://lmu-osc.github.io/introduction-to-renv/caching.html

• [x] typo: For example, if have used {renv} with R versions 4.3 and 4.4 -> if you have used?
• [x] didn't understand this: The {renv} package also provides a function to access the exact path to the cache used in your current project. This cache location will be slightly more specific than the paths listed above because it is a reference to one specific cache, but not all of the caches on your system. You can access the path to the cache with the following code: renv::paths$cache() do you mean 'you can access the cach of a specific project by typing ...? not sure what aarch64-apple-darwin20 is not sure how I would know these paths / which path to look into
• [ ] maybe skip the dplyr cache example
• [x] the whole justification for this page lies in this sentence as far as I understand: "This is an important detail to note for the Restoring Projects section of this tutorial, as you may need to rebuild the cache if you upgrade your R version." - could this be an advanced page, linked in the restore page - 'in the case of upgrading your R version read about that'? and then specify exactly what needs doing? but remove this page from the main tutorial section?

https://lmu-osc.github.io/introduction-to-renv/restoring_a_project.html

• [x] 'Recall from the caching chapter that the renv/library contains “symlinks” to the actual package files on your machine, and these symlinks are not portable across machines' - to remove if caching page moved later
• [x] 'Open the *.Rproj file' -> is this why you recommend to push that file? what if it is not on github? but you create it locally when cloning? would that work?
• [x] 'Place the lockfile in the directory you are working on your project from. This should be a directory with a *.Rproj file.' isn't the lock file supposed to be there already? -> perhaps change to 'make sure the lockfile is in your project directory that contains the Rproj file'
• [x] after reading the section on restore after a R update, I'm still not sure I needed to read the long caching page.

will submit a new issue when going through the exercices.

[NeuroShepherd]

Thanks @MalikaIhle! Will be incorporating feedback today and tomorrow.

FYI for typos and other small changes, creating a new branch and then opening a pull request with suggested changes is probably easier than typing out everything. Here's an example from Florian (who also noted some of the same typo issues as you): https://github.com/lmu-osc/introduction-to-renv/pull/19.

[NeuroShepherd]

(currently at version 1.0.7). -> make this future proof by adding a date or cutting?

Version info is updated automatically.

Self: make sure the GH Action for the website runs every week or so. ^Now scheduled to rebuild the site weekly.

[NeuroShepherd]

didn't understand this: The {renv} package also provides a function to access the exact path to the cache used in your current project. This cache location will be slightly more specific than the paths listed above because it is a reference to one specific cache, but not all of the caches on your system. You can access the path to the cache with the following code: renv::paths$cache() do you mean 'you can access the cach of a specific project by typing ...? not sure what aarch64-apple-darwin20 is not sure how I would know these paths / which path to look into

No. There are (generally) not project-specific caches. The cache(s) specifically works by being shared across projects. I wouldn't expect someone to know these paths hence the explicit mention of renv::paths$cache().

My overall objective with the caching page is to clarify that {renv} creates its own library, and show users where this library/cache is located so they can understand everything a bit more tangibly.

[NeuroShepherd]

the whole justification for this page lies in this sentence as far as I understand: "This is an important detail to note for the Restoring Projects section of this tutorial, as you may need to rebuild the cache if you upgrade your R version." - could this be an advanced page, linked in the restore page - 'in the case of upgrading your R version read about that'? and then specify exactly what needs doing? but remove this page from the main tutorial section?

In general, I think so yes. I've been going back-and-forth on whether to include caching in the main tutorial or in the advanced section anyway. I'll review the page again to see if there's anything that I think is really essential for someone learning {renv} the first time, though.

[NeuroShepherd]

'Open the *.Rproj file' -> is this why you recommend to push that file? what if it is not on github? but you create it locally when cloning? would that work?

Yes, that is why I recommend it. {renv} is realllyyyy intended to be used in conjunction with an .Rproj. If it's not on GitHub, then users should create one locally (and likely push it to GitHub for all project users.)

[NeuroShepherd]

'Place the lockfile in the directory you are working on your project from. This should be a directory with a *.Rproj file.' isn't the lock file supposed to be there already? -> perhaps change to 'make sure the lockfile is in your project directory that contains the Rproj file'

I can try to further clarify this kind of scenario, but essentially the "From a lockfile" section is making the assumption that someone has only provided a lockfile to you via e.g. email or messages or something similar.