[R-pkg-devel] General considerations about vignettes

[Mark van der Loo]

At the cost of some level of reproducibility, you could use a static
vignette and be very clear about the package versions used in the
comparisons:
http://www.markvanderloo.eu/yaRb/2019/01/11/add-a-static-pdf-vignette-to-an-r-package/

As this does diminish the coherence of CRAN somewhat I'm not really
favoring it, but I can see cases where this may be useful (e.g. I use a
static vignette in one pkg to include a published paper).

-Mark

On Fri, Aug 30, 2019 at 5:00 PM Michael Dewey <lists using dewey.myzen.co.uk>
wrote:

> Comments in-line
>
> On 30/08/2019 14:59, Iñaki Ucar wrote:
> > 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.
>
> Yes, but it is widely shared (in the sense that I think it too).
>
> I think the issue here is whether the intention is to compare with a
> particular implementation of a technique in which case you probably do
> need to do what you are currently doing or to compare with the technique
> in general terms. If the latter then Iñaki's solution seems perfect to
> me since even if the package interface changes it still implemented the
> same technique (I assume).
>
> Michael
>
>   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,
> >
>
> --
> Michael
> http://www.dewey.myzen.co.uk/home.html
>
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

	[[alternative HTML version deleted]]