[R-SIG-Mac] Contributing to documentation [Was: Installing gfortran]

[Simon Urbanek]

> On Apr 23, 2022, at 7:44 PM, Patrick Schratz <patrick.schratz using gmail.com> wrote:
> 
> FWIW blog posts which explain such things usually have a (good) reason - they aim to help people getting started when the official documentation is either unclear, hard to find or incomplete.


If that is the case, why not contribute to the documentation? That is the whole point of an open source project after all.

The problem with random blogs is that many of them are written by people trying to find an answer without much knowledge on the subject and often post very bad advice that does not necesarily address the actual issue. There are rare exceptions of knowledgeable people posting explanatory blogs, but if you search for an answer you have no way of knowing whether it is of the good kind. In addition, blogs tend to get out of date quickly, so what used to be a good advice may not be anymore (prime example was the R 4.0.0 release which made a lot of the "hacks" obsolete and the well-meant advice out there has only led to more problems).


> It’s on the readers themselves to decide whether such blog posts are trustworthy or useful.
> 

The problem is that generally they cannot. You are looking something up, because you don't know about it so you can't judge whether it is a good answer (SO is good example proving why crowd-souring the definition of truth doesn't generally work). At best you may know the person and thus judge by that, but even then you may not know if the information is still accurate.


> I have personally profited so often from blog posts of others already and therefore find the general advice to not consult such resources quite shortsighted.
> Of course the official documentation should always be the first point to have a look at - and in this case the required information would have been there.
> 
> Apologies for going partly off-topic but I think this point is important.
> 

I agree. That's why I think it would be great if those that have the knowledge would help the community to improve the documentation. Of all the contributions to R it is the easiest.

That said, I also agree that complementary information is very useful, in particular if it explains the "why" as well - which may be too far out of scope of the canonical documentation. In that case it is easier to spot mismatches, e.g., if it becomes out of date. It is not without precedent to reference such external documentation if it is maintained.

Anyway, I'd like to encourage everyone to contribute - it may be pointing out issues in the documentation or by sending PRs with proposed updates or posting here. Some did in the past (like you, Jan or Bob, thanks!), but the more contribute the better for the community. Often this may also uncover genuine issues that should be addressed rather than worked around (like the lack of the symlink in the gfortran-12 tar-ball discovered just this morning...).

Cheers,
Simon



> Cheers
> Patrick
> 
> On 23 Apr 2022, at 2:13, Simon Urbanek wrote:
> 
>> For posterity - please always consult
>> 
>> https://mac.r-project.org/tools/ (linked from CRAN)
>> 
>> The old locations like libs* are no longer updated and have been deprecated in favor of /tools and /bin which are maintained for all builds. Similarly, I would strongly discourage following any advice from blogs as they tend to be outdated, wrong or both.
>> 
>> Cheers
>> Simon
>>