Project: Improving documentation

[hturner]

Discussed in https://github.com/r-devel/r-project-sprint-2023/discussions/18

^{Originally posted by **giscus[bot]** August 10, 2023} # R Project Sprint 2023 - Improving documentation https://contributor.r-project.org/r-project-sprint-2023/projects/documentation/

[hfrick]

@bastistician 👋 Given that you worked on Rd related things recently, we were wondering if you'd be interested in getting involved with this project here?

[bastistician]

It would have been a real pleasure to meet you all in Warwick! For multiple reasons, unfortunately, my trip had failed. There is definitely room for improvement on some help pages. I had actually proposed a few such changes myself in my pre-R-core life, for example, https://bugs.r-project.org/show_bug.cgi?id=17365. I'm not sure how I could best help remotely now. It would be nice if we could arrange for a video call later today when I could share my thoughts on some specific proposals. Meanwhile, have fun looking at the R sources! :)

[deepayan]

I'm also happy to look at specific proposals at some point.

[hfrick]

Awesome, thank you both!

@bastistician Are you available after 14:00 BST (which is probably 15:00 for you)? I can email you a meeting invite with a video link. (Is Zoom good for you?)

[pmur002]

I have committed (a version of) the proposed patch for Bug 17786 (r85031). Thanks to @MichaelChirico for the original report and patch and to @paocorrales for checking and confirming the patch.

[trangdata]

@bastistician I just submitted a revised patch for Bug 17136. Could you take a look when you have a chance? 🌱

[shannonpileggi]

I submitted a patch for Bug 17933 (paste).

[phillybroadbent]

Overview of remaining documentation bugs

• https://bugs.r-project.org/show_bug.cgi?id=14998 - possibly not a bug and should possibly be closed, needs further consideration.
• https://bugs.r-project.org/show_bug.cgi?id=16963 - existing comments suggest this bug is not correct, so not additions to ?on.exit are supported.
• https://bugs.r-project.org/show_bug.cgi?id=17331 - Removing space and adding quotation marks around the variables CFLAGS and CXXFLAGS is necessary for the code to work, needs additional testing before changing the documentation.
• https://bugs.r-project.org/show_bug.cgi?id=8528 - Martin Maechler has assigned this to himself.
• https://bugs.r-project.org/show_bug.cgi?id=15882 - Needs careful reading and understanding to decide the way forward.
• https://bugs.r-project.org/show_bug.cgi?id=7195 - Changes to R Intro proposed in 2004.
• https://bugs.r-project.org/show_bug.cgi?id=1011 - Changes to R Intro proposed in 2001.
• https://bugs.r-project.org/show_bug.cgi?id=10701 - Changes to R intro proposed in 2008.
• https://bugs.r-project.org/show_bug.cgi?id=7208 - Latest comments propose adding documentation about apply to R intro.
• https://bugs.r-project.org/show_bug.cgi?id=17805 - Has a patch, needs review.
• https://bugs.r-project.org/show_bug.cgi?id=17821 - Patch proposed, requires discussion.
• https://bugs.r-project.org/show_bug.cgi?id=17896 - R-core feedback requested by bug reporter.
• https://bugs.r-project.org/show_bug.cgi?id=16567 - Need to check if this is still relevant after ALTREP.
• https://bugs.r-project.org/show_bug.cgi?id=18026 - writing help page for exportPattern.
• https://bugs.r-project.org/show_bug.cgi?id=18060 - Addition to R-exts, reporter seems to be waiting for support from R core.
• https://bugs.r-project.org/show_bug.cgi?id=18094 - General suggestion for help: ignore case on searches, requires discussion and support from R Core.
• https://bugs.r-project.org/show_bug.cgi?id=18061 - Requires discussion and creation of patch.
• https://bugs.r-project.org/show_bug.cgi?id=16003 - edit to documentation of scale argument on heatmap (possible easy fix for someone with experience using heatmap).
• https://bugs.r-project.org/show_bug.cgi?id=18173 - requires knowledge of lm.fit.
• https://bugs.r-project.org/show_bug.cgi?id=17989 - Comments and confirmation needed from contributers already involved.
• https://bugs.r-project.org/show_bug.cgi?id=18252 - Requires knowledge of encoding.
• https://bugs.r-project.org/show_bug.cgi?id=18282 - Requires discussion.
• https://bugs.r-project.org/show_bug.cgi?id=18330 - requires understanding of install.packages().
• https://bugs.r-project.org/show_bug.cgi?id=18408 - requires understanding of cmake.
• https://bugs.r-project.org/show_bug.cgi?id=18402 - Possibly already solved by commenter, might be able to close.
• https://bugs.r-project.org/show_bug.cgi?id=18499 - Need to review patch.
• https://bugs.r-project.org/show_bug.cgi?id=18524 - Recent suggestion, might need to discuss and get support from R Core.
• https://bugs.r-project.org/show_bug.cgi?id=18561 - Members of R Core have already started working on this.
• https://bugs.r-project.org/show_bug.cgi?id=18567 - patch suggested, large number of files changed so may take a long time to review.

[bastistician]

Thanks for your inputs. In summary, we were able to close the following documentation bugs during the Sprint:

• 17716 (?dyn.load)
• 17786 (?text)
• 17791 (?text)
• 18350 (?c)

The following ones have received patches that are still being reviewed by R-core (or await to be):

• 15272 (?nclass and, more generally, \name -> \alias, is being discussed)
• 17136 (?p.adjust)
• 17695 (?stopifnot)
• 17753 (?ave)
• 17933 (?paste, regarding recycle0)

[paocorrales]

The sprint technically ended but I've just submitted a patch for 17770 (?xtabs)

[bastistician]

Thank you, @paocorrales . The discussion on that will continue in R's Bugzilla now that the Sprint has ended.

@eliocamp : I have just fixed (in c85045) some of the minor doc issues you had raised in your project proposal; there is no need for PRs for these. Thanks!

[MichaelChirico]

https://bugs.r-project.org/show_bug.cgi?id=18418 would have been nice to include here as well (it's marked CLOSED but there's still some discussion about how to improve the docs). I just posted about it to #core-documentation, hope something fruitful can come out of it.

[hturner]

17827 was also closed during the sprint.

As of today (26 October), 17695 and 17933 are closed, the remaining patches are under discussion/awaiting review.