[Rd] Heads up about documentation-related reports

[Elio Campitelli]

Thans for the response, Martin.

I've updated the project web page to focus first on the existing bugs and filling new ones, without mention of examples: https://contributor.r-project.org/r-project-sprint-2023/projects/documentation/
The idea was not about removing complex examples but about adding simple examples. Complex examples can be useful to surface advanced functionality or neat usages of a function, but simple examples illustrate basic functionality, particularly for beginners who need to understand how a function behaves in its most simple case before being able to understand any more interesting behaviour or interaction with other functions. That's one criteria for "better" in this context.
Cheers,
Elio

On Aug 16 2023, at 5:29 am, Martin Maechler <maechler using stat.math.ethz.ch> wrote:
> >>>>> Elio Campitelli
> >>>>> on Mon, 14 Aug 2023 17:42:42 -0300 writes:
>
> > For the upcoming R Sprint I'm proposing a project to improve documentation
> > <https://contributor.r-project.org/r-project-sprint-2023/projects/documentation/>.
>
> That's good, thank you.
> However, do concentrate on the existing bugzilla issues
> https://contributor.r-project.org/r-project-sprint-2023/projects/documentation/#list-of-bugs
>
> (and can you *PLEASE* (change the CSS or ?? to) make the table
> of relevant bugzilla entries wider so it becomes readable ?!)
>
> > Part of the project will include several small related reports; for
> > instance, trying to improve examples of many functions (here's a list of
> > some of the possible reports
> > <https://contributor.r-project.org/r-project-sprint-2023/projects/documentation/#bugs-to-report>
> > ).
>
> > Would it be better to send one single big report or many small reports?
> > Cheers,
> > Elio
>
> {Do you mean bugzilla bug reports?
> In that case, maybe rather *none* [see also below]:
> If you do not like an example that is definitely not a bug in R!
> ---> https://www.r-project.org/bugs.html "What is a bug"
>
> Also: Every bugzilla report (and comment) creates an e-mail to
> all of R core. Yes, we can sort / pre-filter /
> .. e-mails, but still
> }
>
> Well, as co-author of many of R's help page examples, I must say
> that "improving" an example needs to have a well defined notion
> of "bad - better - good" etc.
> In my opinion much of that is a matter of taste rather than objectivity.
>
> As an R core member I'd not like you to propose changing
> examples I or others had chosen to be "funny" , "cute",
> "special", or "thought provoking" ... just because other people
> think that such examples should be as simple (and boring) as possible.
>
> I hope the helpers at the upcoming R Sprint will concentrate on improving R
> by following what R core member Luke Tierney and Tomas Kalibera
> wrote in their two R blogs:
> ==> https://blog.r-project.org/
> and look for the 2 blog entries with "Reviewing Bug Reports"
> in their title.
>
>
> I'm sorry if the above does not sound encouraging..
> I hope it still does encourage to rather concentrate on helping
> to make R better by reviewing bugs, fixing bugs, exploring
> problems, etc.
>
> With regards,
> Martin
>


	[[alternative HTML version deleted]]