[R-pkg-devel] Require <package>-package.Rd?

[Viechtbauer, Wolfgang (SP)]

Hi Dirk,

Point well taken, but the same goes for many other CRAN requirements. For example, I can create totally useless help files for all the functions that pass all checks. Just because some will try to skirt around a requirement doesn't mean it's a useless requirement. In fact, the point of such requirements is to promote good practices and I would like to believe that most package authors would make an honest effort to create a somewhat useful <package>-package.Rd file, even (as Joris pointed out) it is essentially just a pointer to the vignette(s) (which is also useful).

Best,
Wolfgang

-----Original Message-----
From: Dirk Eddelbuettel [mailto:edd using debian.org] 
Sent: Tuesday, 24 September, 2019 14:39
To: Joris.Meys using ugent.be
Cc: Viechtbauer, Wolfgang (SP); r-package-devel using r-project.org
Subject: Re: [R-pkg-devel] Require <package>-package.Rd?

Wolfgang, Joris,

This may not necessarily work -- see "Goodhart's Law" [1]

Once you impose something like this, (some) will skirt it with just the
minimum requirement of an (essentially) empty file.  An existing set of
examples is provided by the vignettes of (at least) one developer which each
consist (or consisted ?) of just a single line with a hyperlink to the
corresponding package website.  Passes the letter of the law (hey, look, a
vignette) and all possible tests, but clearly violates the spirit of the law
that documentation and package should be self-contained (and no, connectivity
should not be assumed).

Moral persuasion may be better. We should encourage best practices and
highlight packages that follow them.

Dirk


[1] https://en.wikipedia.org/wiki/Goodhart%27s_law

-- 
http://dirk.eddelbuettel.com | @eddelbuettel | edd using debian.org