[R-pkg-devel] General considerations about vignettes

[Michael Dewey]

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