Strategies to write documentation

[Rekyt]

Topic

Documentation in R comes in many forms: documentation of functions, packages READMEs, vignettes, even entire manuals (i.e., for drake, taxize, or rmarkdown). To increase the reach of packages documentation is paramount. rOpenSci provides recommendations on what should be comprised by the documentation. However, when (during package development, at the start) and how (how should it be framed? should we prefer a use-case, a manual, or a reference? To whom are we writing the documentation for?) to write documentation hasn't been discussed in our community.

In addition to tools that are becoming standard among R package developers like roxygen2 or pkgdown several other R tools that can help write documentation could be discussed:

• Rdpack to easily add references to documentation,
• sinew to automate even more writing documentation,
• roxytext to use documentation as a test case.

Different strategies to write documentation could also be discussed. Don't Repeat Yourself (DRY) when writing documentation, but sometimes Do Repeat Yourself so that the user can always figure out where to go. Can we adapt the "Documentation-first" strategy (also named Documentation-Driven Design) when it comes to R packages?

Who is the audience?

All R package developers and potential contributors. Writing documentation is one of the non-technical contribution that a user can provide to a project, as such this community call can address to anybody who's willing to contribute.

Why is this important?

Because rOpenSci enforces great standards in documentation. Explicit discussion on strategies to write documentation could also greatly benefit onboarding packages developers.

What should be covered?

1. Distinction between different types of documentation (function documentation, package documentation, README, vignettes, Use-case, manuals, blogpost) and how they can be viewed by typical users of the package (i.e, where does the journey of user begins in the documentation).
2. Strategies to write documentation. How should documentation be structured? Where can it be repeated? How to maintain documentation updated with an evolving package?
3. Tools to help write documentation.

Suggested speakers or contributors

Folks that have written extensive documentation packages (such as @wlandau, or @maelle who can share her experience writing a whole book on http-testing). People from ReadTheDocs?

Resources you would recommend to the audience

• The vignettes from roxygen2,
• https://www.writethedocs.org/ the website from the people behind ReadTheDocs that offers many useful resources to write documentation.

[maelle]

Other potentially relevant resources

• The documentation system
• What Docs When

[stefaniebutland]

Beautifully laid out idea @Rekyt. Thank you! I'm working on others now but this is def a good candidate rOpenSci Community Call.

[stefaniebutland]

Resource

• Daniele Procida on "frameworks for documentation". One of his youtube talks here: https://www.youtube.com/watch?v=t4vKPhjcMZg

h/t @choldgraf (Project Jupyter) who is gauging interest in a virtual workshop on documentation for people in the NumFOCUS community (NumFOCUS is rOpenSci's fiscal sponsor).

[maelle]

@stefaniebutland same link as the first I listed... but with a much more informative presentation :grin:

[stefaniebutland]

🤦🏼‍♀️ 🙌🏼 🤦🏼‍♀️

[maelle]

No, it's good to have a better explanation of the link!!

[stefaniebutland]

New home for Diátaxis Framework https://diataxis.fr/ by Daniele Procida