[R-pkg-devel] General considerations about vignettes

[J C Nash]

I'm seeking some general advice about including vignettes in my packages,
which are largely for nonlinear estimation and function minimization (optimization).
This means that my packages offer alternatives to many other tools, and the user
then has the chore of deciding which is appropriate. Bad choices can be very
costly in inappropriate results or computational efficiencies. Hence, I include
vignettes to offer comparisons and examples of use.

Unfortunately, as in a case this week, changes in the comparison packages break
my package(s), and I get an email from CRAN telling me to fix it before some
date not far in the future. This means a) work for me, possibly at an inopportune
time; b) risk of loss of capability, in the present case in the nlsr package which
offers some unique capabilities, and c) extra work for CRAN for what is, arguably,
updating of peripheral documentation. Updating optimization packages on CRAN can be,
I have discovered, a very time-consuming task. Package optimx took over 3 months
to get updated.

It should be noted in the present situation that just before I got the msg from
CRAN I got a msg from the maintainer of the package that has changed and breaks
the vignette with some suggestions on a fix. The issue is that his package has
changed function syntax -- a situation all of us know is fraught with troubles,
since improvements may cause breakage.

I am NOT saying that my vignettes should not be updated. However, I'm wondering
if I should set up a repository for my vignettes on Github/Gitlab or similar, and
simply link to them. This would separate the updating of vignettes from the central
packages. Their updating could be less strictly tied to CRAN activities, and could
also be a task undertaken by others who are not listed as maintainer.

I'd welcome some (hopefully constructive) comments. Would CRAN maintainers feel
this to be helpful, or does it lower the value of official R packages? Do
other maintainers experience the same requests, or do they just not include
vignettes (and many do not)?


John Nash