Example usage questions

[wjakethompson]

JOSS review criterion: Example usage (openjournals/joss-reviews#5835)

Example usage in the vignette currently points to external documents. These documents do a good job of illustrating example uses, but some were create many years ago (e.g., 2018). Is the functionality in those older documents still accurate, or have updates to the package in the last 5 years made those example obsolete? On the other hand, will future changes to EdSurvey potentially make current examples irrelevant.

Ideally, each of the example uses would be included as a vignette in the package (or an article that is only rendered on the pkgdown site if they are too big for CRAN). This would ensure that all the examples still work with the current version of the package, and would also ensure that future updates don't break the example (or that the examples are updated to reflect the updated package).

[pdbailey0]

Thanks for pointing this out. EdSurvey was taking too long to build on the CRAN servers and was getting close to oversize, so we removed the vignettes to comply with a request from the CRAN maintainers to make it build at least two times faster.

The pkgdown site is an interesting alternative. We're actually moving our documentation to a book in package down. @wjakethompson If we updated the vignette to link there would that alleviate your concerns? Or are you saying it would be part of this site?

[Edited by PB to fix link formatting.]

[wjakethompson]

I think in an ideal world it would be part of pkgdown site directly. If the example uses are part of the package itself, then they will be rebuilt whenever the package is updated, and throw and error if any of the changes to the package have broken the example use. This way, you would always know that the example uses were up to date with the current version of the package.

However, if EdSurvey is stable at this point and you aren't anticipating many updates in the future, then I think the bookdown site is sufficient.