r-devel / rcwg

R Contribution Working Group: fostering a larger, more diverse community of contributors to R core development
https://contributor.r-project.org/working-group
68 stars 17 forks source link

Some more comments on the draft #55

Open MichaelChirico opened 7 months ago

MichaelChirico commented 7 months ago

Not sure the right way to make suggestions without strictly committing to an edit for a PR. So filing this issue with comments on permalinked source. Happy to file a PR with accepted suggestions/adjustments, starting here for discussion.


https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L11

Maybe drop "small"? I worry it might diminish the work that got completed, some of which was low-hanging fruit but some of which I would shy from calling "small", though it is definitely "relatively small" compared to those tasks where significant headway was made without reaching the finish line. How about

Several tasks were completed during the sprint itself. Some larger projects saw significant progress as well.

https://github.com/r-devel/rcwg/blob/main/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L13-L15

A bit repetitive "development"/"develop", "contributors"/"contribution". Maybe

The event provided a unique opportunity for external programmers to learn about the R development process and to further their contribution skills.

https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L57

Here and a sporadically below, the line is very wide, so it's harder to read in plaintext. It doesn't matter for the rendered version.

https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L60

Nit: elsewhere, numbers are digits, here it's spelled out. For consistency 'seven' -> '7'.

https://github.com/r-devel/rcwg/blob/main/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L133-L135

Nit: the two 'and' are a bit hard to parse, maybe

including the R Blog post on reviewing bugs, the useR! 2021 tutorial on analysing bugs/contributing patches, and the useR 2021! tutorial on translating messages in R.

Or

including the useR! 2021 tutorials on analysing bugs/contributing patches and translating messages and the R Blog post on reviewing bugs.

https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L144

Does Coventry use the Oxford comma? :)

https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L144-L147

Grammar feels a bit off in the late part of the sentence, what about

People new to this were pointed to the R-admin manual, the R Dev Guide, and a prototype GitHub Codespace for building R which was demonstrated in one of the contributor office hours[^footnote]. [^footnote] GitHub Codespaces provide hosted Docker images so that anybody can use the same environment from anywhere, see https://github.com/features/codespaces.

https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L158

I would change 'this was followed' -> 'followed'. Possibly a UK/US thing.

https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L168

Add a phrase on "what is translation memory?"

https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L169

Probably not clear what a component is? Maybe drop the phrase entirely?

The instance was extended so that it not only covers base R (messages, warnings, errors and the Windows GUI), but also the Mac GUI and recommended packages.

https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L171

May not be clear to the audience "recommended" is a specific phrase here. Maybe "Recommended-priority packages" is better, or "Recommended-priority packages like Matrix" for even more context?

https://github.com/r-devel/rcwg/blob/dc996608da51f8b7fa3acf1fd8d2aaf04440b92b/r_project_sprint/report/r-project-sprint-2023-report.Rmd#L209

Typo: 'sprint'