[R-pkg-devel] General considerations about vignettes

[Iñaki Ucar]

On Fri, 30 Aug 2019 at 15:26, J C Nash <profjcnash using gmail.com> wrote:
>
> 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)?

My two cents:

For me, as a user, vignettes are the most valuable form of
documentation in a package. Of course, this is personal opinion. But
these days with so many good packages out there, I don't have time to
install all of them and dive into the manual and the examples just to
decide which one is better for my use case. A good written vignette
most of the time is my driving factor (sometimes, if it's a small
package with one particular functionality, a good README is enough,
but that's not the case here).

Thus, as a maintainer, I try to lead by example. It's time consuming,
but on the other hand, many times a help request by a user can be
resolved with "please, take a look at section x of vignette y".

One thing I do to make them as maintainable as possible is to try to
avoid dependencies on third-party packages as much as possible. In
your case, comparing yourself with other alternatives may be
important. I'd suggest to set eval=FALSE for chunks with expensive
demonstrations of other packages, and then show a static figure with
the comparison that you made once, but doesn't need to be recreated
each time the vignette is built. In this way, issues like the one you
described won't affect your package, at least immediately. Until some
user reaches you to say, hey, I've tried the code in this vignette for
package x and it doesn't work for me. Then it's time to revisit that
code and rebuild the figure.

You could have vignettes that you don't rebuild constantly in a
separate repo and link them from a main vignette on CRAN, but that's
no different from what I propose above, and it's one click away.

Hope it helps. Regards,
-- 
Iñaki Úcar