[Rd] Heads up about documentation-related reports

[Martin Maechler]

>>>>> 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