The examples section of every base-R function's help page are just the WORST. #rstats
For example: https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/switch
@capbri I respectfully disagree, they have their own style that **now** I like.
I think the public they targeted long time ago is not the same anymore.
I am hoping that great project like this: https://ropensci.org/blog/2024/07/09/multilingual-documentation-wg/
can be used to add different flavors on help page.
@defuneste I hear you. My big gripe with base-R help (and the help in many packages) is that they create abstract, toy datasets to explain features (columns “A”, “B”, “C”; rows 1, 2, 3). Base-R has plenty of built-in datasets of concrete case examples. Why aren't we using *actual* data in examples, instead of confusing abstract toy examples? If I'm looking for help, the *last* thing I want is abstract data I can't make sense of being used to demonstrate a function I can't make sense of. #rstats
@ingorohlfing @capbri @defuneste as a person new to R, I have to agree base docs are complete in an abstract sense (insofar as they do document thoroughly which cannot be said of all languages or frameworks), but they are hard to understand. I've found that tidyverse docs and the Advanced R book helpful such that I "get" what some base doc means.
@defuneste Also, this complaint isn't restricted to R. I have the same gripe about #pandas in #python. The base pandas examples—unless they've drastically changed—often use toy datasets that are *super* confusing. In the case of pandas, I'm not sure whether it ships with concrete datasets. But, like, base-R has chickwts, mtcars, etc. Almost any of those—rather than toy datasets—can be the basis for showing the user how to do complex manipulations/use base-R functions.
@capbri the goals of it being abstract is that you should build abstraction also or small reproducible example. Still I agree with you it could be good to use some classic data set.
@capbri @defuneste I am with you on much base R help information. They are very often cryptic and not illustrating simple, basic usage that most users are likely to look for