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 at gmail.com> wrote:
I'm seeking some general advice about including vignettes in my
which are largely for nonlinear estimation and function minimization
This means that my packages offer alternatives to many other tools, and
then has the chore of deciding which is appropriate. Bad choices can be
costly in inappropriate results or computational efficiencies. Hence, I
vignettes to offer comparisons and examples of use.
Unfortunately, as in a case this week, changes in the comparison
my package(s), and I get an email from CRAN telling me to fix it before
date not far in the future. This means a) work for me, possibly at an
time; b) risk of loss of capability, in the present case in the nlsr
offers some unique capabilities, and c) extra work for CRAN for what
updating of peripheral documentation. Updating optimization packages on
I have discovered, a very time-consuming task. Package optimx took over
to get updated.
It should be noted in the present situation that just before I got the
CRAN I got a msg from the maintainer of the package that has changed
the vignette with some suggestions on a fix. The issue is that his
changed function syntax -- a situation all of us know is fraught with
since improvements may cause breakage.
I am NOT saying that my vignettes should not be updated. However, I'm
if I should set up a repository for my vignettes on Github/Gitlab or
simply link to them. This would separate the updating of vignettes from
packages. Their updating could be less strictly tied to CRAN
also be a task undertaken by others who are not listed as maintainer.
I'd welcome some (hopefully constructive) comments. Would CRAN
this to be helpful, or does it lower the value of official R packages?
other maintainers experience the same requests, or do they just not
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,