vignettes

[connor-french]

I split this issue from the documentation review checklist because I believe it needs its own space. Right now we have in introductory vignette and a "use cases" vignette. I think splitting the "use cases" vignette so each vignette is its own use case makes it easier for users to find what they need and makes the docs more navigable. I think the slendr package does a great job with their documentation, so I think they're good to emulate. Here's how I see the documentation organized:

1. Index/README

   • Overview
   • Main features
   • Installation
   • Basic run-through
   • More information (role-model website, roleShiny, pointing to other vignettes)

2. Introduction and basic tutorial

   • Motivation
   • Installation
   • Basic run-through (repeated from index so it's easily discoverable within the package)
   • More information

3. Use case 1

   • Purpose of the vignette/overview (no heading, just the intro text)
   • Example of the use case

4. Use case 2, etc.

[jidec]

I like this outline! a question for everyone is what the "use cases" should actually be

[Rilquer]

Thinking of "use cases", I believe it'd be useful to have one for each dimension that can be modeled. What comes to my mind:

1. Maybe one use case showing how the RoLE model can reproduce classic island biogeography theory (i.e., richness vs size and isolation)? Or maybe this could be a basic example shown in the intro, and the use cases could expand on all the dimensions that the role model allows the user to incorporate when modeling a community.
2. One use case exploring the phylogenetic parameters used in the model and how they interact (so people have a clear example to understand how changing these parameters affect the modeling)
3. One use case about non-neutral assembly and traits, explaining the parameters related to traits (i.e., neutral vs non-neutral knob, competition/filtering knob).
4. Popgen example.
5. Maybe an example with bridge islands as the init_type and how that affects the modeling