Better documentation for R-universe!

Since the initial launch in 2021, our R-universe platform has steadily grown into a comprehensive infrastructure for publishing and discovering R material. As functionality keeps evolving and community adoption increases, we felt the need for a central documentation point.

New features and developments are generally discussed in the issue tracker or discussion board, and sometimes on the rOpenSci blog. Technical details can be found in the README files and source code of the respective repositories under r-universe-org that contain all the workflows, actions, and server code (the R-universe system is entirely open source). This fragmentation can make it difficult to find up-to-date information, especially for new users.

Thanks to funding by Google Season of Docs, we were able to start a new comprehensive documentation project for all users and developers of R-universe. We established a central place where we collect the various sources of information and describe examples and use cases, using popular authoring tools to support collective maintenance.

🔗 New r-universe docs

The new R-universe documentation website is now live at https://docs.r-universe.org. You can find the source code on GitHub.

We created it as a Quarto book as this is a common format that many members of the R community are used to reading (for instance in R Packages, R for Data Science, our development guide¹) and can contribute to.

The documentation is currently organized into four main sections:

• Browse that documents the user experience navigating packages and universes.
• Install that explains how to install packages from R-universe, how to ensure reproducibility, and how to create a dependency on a package published on R-universe.
• Publish that focuses on the package developer experience: why and how to publish packages.
• Infrastructure, documenting governance, funding, and how R-universe works under the hood for those who want to contribute. (A work in progress!)

In addition the website has search functionality, and features links to the GitHub repository where you can contribute to the documentation.

We are thankful to the documentation reviewers Lluís Revilla and Yaoxiang Li who provided insightful feedback that helped us improve the initial version of the website.

🔗 Interactive website tour

Besides a new docs site, we also added some embedded documentation into the website: each package page has a “Website tour” button in the navbar, that guides you through all the information displayed on the page. Go give it a try!²

🔗 A streamlined docs experience

While working on the documentation we also updated other information sources:

We simplified the R-universe project page on the rOpenSci website the be easier to maintain. It now contains a big-picture description of the project, as well as links to relevant resources including the documentation website, technical notes, recent talk recordings. That web page is also available in Spanish.

The README on the organization profile on GitHub was updated to list relevant websites and online spaces such as the docs, obviously, but also the discussion board and general issue tracker. The former FAQ list was retired and replaced with links to relevant docs chapters, and references on where to get help and participate to the project.

🔗 Conclusion

The new docs project will become the central place where we maintain up-to-date information for users and developers of R-universe. The initial version of the site has the most important bits, but is far from complete. Just like R-universe itself, the documentation is a living project that has to grow iteratively based on your needs and contributions.

If you have used R-universe in one way or another, and have ideas on how documentation could be improved, we welcome your contributions.