thibautjombart
commented
2 years ago Thanks for starting this conversation - very important topic. The section on documentation in our blueprints is but a place to start. Some thoughts below.
-
I found diataxis provides a useful framework for thinking documentation; would be great if you could check it out and share your thoughts; following that framework, I would say:
- reference: done via roxygen2 - this is basically the Rd files and corresponding 'Rerefence' section in a pkgdown website; must-have for package release
- howto guides: should be vignettes and come by default with the package, a minimal one being an 'Introduction' vignette for the main package functionalities; and possibly others to cover common use-cases into more detail; I would put it down as must-have for package release
- tutorials and explanations: could also be vignettes, or training material hosted separately from the package; not sure if we want to make it mandatory as part of the packages; good to have for package release, but not mandatory?
-
For now it seems rmarkdown and pkgdown are the common standards, but Quarto may be set to take over; I guess it depends on the extent to which quarto is stable at the moment; @Bisaloo I know you are interested in Quarto, would be good to hear your thoughts.
Is there a consistent long-form documentation structure we want to enforce in epiverse? In other words, do we have a checklist that each package should comply with, for example do we want to use Pkgdown for every package, or should every package have at least one vignette? If so should this be an introductory vignette to the basic functionality? In terms of vignettes I have previously found that diversity of functionality and intended audience (R beginners vs experienced R programmers) determines how many vignettes to write. Additionally, is there a recommendation on how we should write these? I have not yet used Quarto, if anyone has experience with this it would be good to hear their thoughts and whether they recommend it. I do not have a personal preference on whether we standardise the long-form documentation.