search

samhforbes / PupillometryR

An R package for preparing and analysing pupillometry data
Other
42 stars 4 forks source link

Move most readme content to a vignette #9

Closed drmowinckels closed 4 years ago

drmowinckels commented 4 years ago

This is an opinion, so it can absolutely be discussed.

in my opinion, the readme as a whole should be moved into a vignette folder and be compiled as such. This will also then run the vignette code during build checks, making sure that the vignette is actually executable (easiest way to do so it to use usethis::use_vignette() ).

The readme should be made concise and rather highlight what the package intention and core features are, while a full user tutorial is best placed in a vignette.

samhforbes commented 4 years ago

I really appreciate the benefit of your experience here @Athanasiamo. As you have suggested, the README has been simplified, with the expanded walkthrough moved to vignettes. In line with the other issues you've raised, the other tutorials are linked, community guidelines are flagged, and installation instructions are (hopefully) clear - more in line with the usethis templates. I have included badges to note the travis-CI and CRAN status as well.

drmowinckels commented 4 years ago

This looks much neater in my opinion. Great you also added some badges indicating CRAN and CI status.

as a complete sidenote and something not related to the review, but something you might consider, is using pkgdown to generate a site for your package. https://pkgdown.r-lib.org/articles/pkgdown.html Your package is set up correctly, meaning there is little you have to do to get it working. For people looking for your vignette for instance, it might be more convenient to see it hosted online (though github pages).

But, this is purely a suggestion. As a developer though, I can say that I have often linked to the online vignettes rather than the vignettes shipped with the package. Particularly for developer updates not yet available on CRAN.

samhforbes commented 4 years ago

This is a great suggestion, and again, thanks for the advice. I'm going to leave this open temporarily as a reminder to devote some time to getting a (pretty) page going

samhforbes commented 4 years ago

It's pretty! This is now up - currently at samforbes.me/PupillometryR