Move documentation examples to vignettes

runapp-aus / strayr

A catalogue of ready-to-use ABS coding structures. Package documentation can be found here: https://runapp-aus.github.io/strayr/

45 stars 14 forks source link

Move documentation examples to vignettes #41

Closed bryceroney closed 3 years ago

bryceroney commented 3 years ago

I was thinking as the functionality of the package grows, we could end up with a pretty long README so we could move them to vignettes and then reference in the README.

Any issues with that?

MattCowgill commented 3 years ago

It'd be good if the README still gives a sense of what the package can do, but I agree it doesn't need comprehensive documentation of every function

daviddiviny commented 3 years ago

Agree.

Maybe it should provide an overview of the overall structure of the package and the families of functions within:

Data
Cleaning
etc

bryceroney commented 3 years ago

Yes, agreed with both above. I think the Tidyverse packages find a good balance between detail and summary.

bryceroney commented 3 years ago

Have been thinking also, some of the documentation could be handled by the actual reference documentation, e.g. the public holidays data.

wfmackey commented 3 years ago

I agree with all of the above. Maybe:

README: outline of package, summary of families of functions
- 'hey these functions/datasets exist'
vignettes: detailed (but not exhaustive) demonstrations of function/dataset use (similar to what is in README now)
- 'hey this is how you might use the functions/datasets, or how you would contribute to this package'.
package documentation: exhaustive detail.

mrjoh3 commented 3 years ago

In pkgage down the general use case is, the readme is for installation instructions and enough detail for people on github. Then you have a vignette with the package name that has more detailed information, then additional vignettes for specific topics.

I thought I had setup a vignette with the package name but had not added content yet. I will get this setup and report back

wfmackey commented 3 years ago

Thanks @mrjoh3, @bryceroney and @MattCowgill for putting this together in #49 . Now to write some more vignettes!