Improving documentation
Problem statement
In general R documentation is very good and thorough, but there’s always room for improvement.
Right now there are 43 documentation-related bugs open in Bugzilla. Searching online and asking on social media also brings up more documentation issues that could be discussed—and possibly eventually fixed.
Proposed workflow
Triage existing bugs
A first pass would be to triage bugs in the Documentation tag in Bugzilla.
Find new bugs
A second pass would be to look for new documentation issues and open bugs on Bugzilla where there is agreement the documentation could be improved.
Sources for these issues can be:
- Ask among R Contributors.
- Ask on social media.
- Search the R documentation of functions that beginners might need documentation for, such as
mean(),sd(), etc. - Look for R scripts on GitHub and tally the most used functions and evaluate their documentation.
List of bugs
This table lists all currently open bugs with the Documentation tag sorted from oldest to newest (based on last comment). The “Location” column specifies which documentation is affected. The “Affected users” specifies which type of user I think are most likely affected by the issue (Beginners: people just starting with R, Advanced: people that use R regularly, Experts: people in close contact with R internals and/or package development). The “Action(s)” column lists the required actions to address the bug. And the “Comments” column is for general comments about the issue.
Bug ID |
TitleSuggestion for two internal self-reference in “Writing R Extensions” manual |
LocationWriting R Extensions |
Affected usersExpert |
Action(s)discuss |
CommentsSuggests adding a sentence to “Writting R Extensions” linking to other sections. Not very clear on what the issue is. |
Status |
|
| 16963 | In ?on.exit, add note that on.exit expressions are evaluated after return() call. | Help docs | Advanced | create patch | A note about a relatively obscure but potentially important quirk of on.exit(). |
||
| 17136 | Documentation for method=“BY” in p.adjust() | Help docs | Beginner | check patch | Clarifies the behaviour of p.adjust(). Patch includes fix. Might need to read up p.adjust()’s source code and the relevant papers to confirm. |
New patch submitted @trangdata |
|
| 17331 | Inappropriate implicit variable setting in ~/.R/Makevars macOS recommendation | R Installation and Administration | Advanced | check patch | Need a Mac to confirm. A possible fix is included in the bug report. |
||
| 8528 | pgamma - inadequate algorithm design and poor coding | ||||||
| 15882 | [requires a positional argument, not mentioned in docs | R Internals | Advanced | discuss create patch |
|||
| 7195 | additional examples for R-intro.texi | An Introduction to R | Beginner | review patch | Adds a bunch of text to this guide. Includes a patch. Might need to review what changed since 2004 when this was proposed. | ||
| 1011 | R-intro suggestions part II | ||||||
| 10701 | Suggestions for R-intro manual | ||||||
| 988 | input for R-intro | ||||||
| 15272 | ?nclass doesn’t find the nclass help page | Help docs | create patch | The issue is confirmed and trivial to fix. | @eliocamp Submitted patch to fix the trivial issue but more deep issue found. |
||
| 17695 | stopifnot example does not run all the way through | Help docs | Beginner | discuss create patch |
This seems to stem from the code in the example() function and thus the core fix needs fixing that. That might be hard. OTOH, a simpler fix would be to add a note in the example section. That’d be trivial. |
@eliocamp Submitted patch to solve the immediate issue. New issues found. |
|
| 17716 | Small documentation pass on ?dyn.load | Docs | Expert | check patch | This includes a patch to fix small typos and grammar mistakes in the docs. Needs a quick revision to confirm that nothing’s changed and then it could be approved by core. | patch checked @hfrick |
|
| 17753 | ave() documentation misleading | Help docs | Beginner | create patch | The bug is valid and current. The report includes proposed changes but not in patch form. | patch created @paocorrales @phillybroadbent | |
| 17786 | ?text can clarify the adj argument | Help docs | Beginner | check patch | A patch is provided. Needs to be checked for accuracy and it’s good to go. | bug closed @paocorrales |
|
| 17791 | ?text doesn’t have any vfont examples, and doesn’t link to the Hershey help page | Help docs | Beginner | check patch | A very simple fix with a valid diff. | ||
| 7208 | Documentation R-intro input | An Introduction to R | Beginner | discuss write new documentation create patch |
This report points out the lack of examples of some potentially useful functions in this document: sweep(), apply(), lapply() and sapply(). It would need a bunch of writing and coming up with good examples. |
||
| 17805 | args(): document NULL return value for certain special primitives | Help docs | Advanced | check patch | Involves a particular edge case for a relatively obscurse function. Has a patch (although it might need revision). | ||
| 17821 | Reference possible portability issues for translations in R-Exts | Writing R Extensions | Expert | check patch | Patch is there to apply. | ||
| 17827 | Request to remove Annals of Eugenics citation from iris documentation | Help docs | Beginner | discuss (a lot) create patch |
This is mostly a social thing and I think it requires a lot of discussion with the community. | @shannonpileggi reviewed and suggested to close. | | | |
| 17896 | Cleaning up Internationalization section in R-exts | ||||||
| 17933 | ‘paste’ doc: wrong: 0-length arg recycling related to ‘collapse’ | Help docs | Beginner | check patch | There’s a patch with a fix. | patch submitted @shannonpileggi | | |
| 16567 | Claims about computational complexity of findInterval | Help docs | Advanced | discuss create patch |
We need to check if this is still relevant after ALTREP. | ||
| 18026 | Include help page for exportPattern | Help docs | |||||
| 18060 | “Malformed maintainer field.” message could be more helpful | Help docs | Expert | discuss write documentation create patch |
This requires to create whole new documentation pages for the functions used in NAMESPACE. | ||
| 18094 | Suggestions for help system | Help docs | Beginner | discuss create patch |
This would involve creating new aliases for a bunch of help pages. Not hard, but debatable. | ||
| 18061 | The documentation is not clear that match() does not use the same notion of equality as unique(). | Help docs | Beginner | discuss create patch |
|||
| 16003 | heatmap scale argument: description not complete | Help docs | Beginner | create patch | |||
| 18173 | Man page for lm.fit is very brief about the circumstances when to use | Help docs | Advanced | discuss create patch |
Needs some understanding of the lm.fit function and friends. |
||
| 17989 | Documentation of asCall argument to xgettext is unclear | Help docs | Expert | check patch | |||
| 18252 | Document how unicode strings are compared for equality | Help docs | Beginner | check patch | Needs some knowledge about encoding. | ||
| 18282 | Description of var.test for lm objects could be improved. | Help docs | Beginner | create patch | |||
| 17279 | parameter “amount” is badly explained for jitter() | Help docs | Beginner | check patch | |||
| 18330 | type argument documentation in install.packages | Help docs | Advanced | discuss create patch |
Requires some understanding of packaging. how install.packages() work. |
||
| 18355 | trace() wipes out attributes | Help docs | Expert | discuss create patch |
This is actually a bug in the function. It might be better to fix that bug instead of documenting the wrong behaviour. | ||
| 18350 | Clarification needed in ?c | Help docs | Beginner | check patch | patch is accurate, comment submitted to bugzilla | @phillybroadbent |
||
| 18408 | Using CMake section “$(SHLIB): mylibs” did not work for me | Writing R Extensions | Expert | discuss create patch |
Needs knowledge of cmake. | ||
| 17770 | xtabs does not act as documented for na.action = na.pass | Help docs | Beginner | discuss close issue |
The issue seems to be solved by a previous patch. | original issue was solve. patch for new issue in progress @paocorrales |
|
| 18402 | Provide a mechanism for adding custom CSS styles to HTML documentation headers. | ||||||
| 18499 | Examples for functions that involve writing files | Writing R Extensions | Advanced | check patch | |||
| 18524 | DOCS: Make it easier to find help on raw string constants, e.g. help.search(‘r”’) | Help docs | Beginner | check patch | |||
| 18561 | \item{} labels processed inconsistently in \value{} between Rd2HTML and other converters | discuss | |||||
| 18562 | Ambiguous statements in write() help page | Help docs | Beginner | check patch | Done? @mmaechler committed an improved version of write.Rd on 2023-07-31 |
||
| 18567 | Consistent style in base package help pages | Help docs | check patch |
Bugs to report
These are possible issues to post on Bugzilla after discussion.
- The documentation of
p.adjust()shows that the default value ofnislength(p). However, this is evaluated afterNAs are removed fromp, so this is not technically correct.
In
?residualsmake it clear that both functions “are intended to encourage users to access object components through an accessor function rather than by directly referencing an object slot”.- “It is intended…” to the end of the paragraph? Maybe not, resid should be mentioned before the paragraph about method registration. I am no longer sure if a change is needed. The help page for ?f itted is very similar btw, it just doesn’t talk about accessor functions. Maybe just replace “It is intended to encourage users” by “User are encouraged”? (A formal patch is not needed, we can discuss)
?matchsays “%in%is a more intuitive interface”, butmatch()and%in%return different things.- TODO come up with a succinct description of %in% that is correct
Add examples of the
\(x)function interface to thefunctionhelp page.- TODO add a short example
Explicitly state that
remove()is an alias forrm().Document the differences between factors and ordered factors in models (https://mastodon.social/@mccarthymg@fosstodon.org/110685274281599336) .
- bigger discussion to have: we have some support from Thomas Lumley; BUT: this is just a note in factor’s documentation, not on the model side. https://github.com/r-devel/r-svn/blob/5ec122aee4f616d6cc6bcd6479d1edcc45a7c5ea/src/library/base/man/factor.Rd#L116C3-L117. add a link to related functions: contrasts, model.matrix; could link to contrasts options but not feeling very strongly about this
The
?irisexample section doesn’t seem to be very useful. I don’t understand what its doing. (Not discussed!)?formulashould link to?update.formula. (Not discussed!)
Project requirements
This project is open to anyone with working knowledge of R.