Migrating our Group Procedures to Quarto
When I first started at CCT, our group procedures (e.g. onboarding/offboarding, meeting structures, policies, etc.) were housed in an OSF wiki. This was great because pages were simple markdown and were easily editable on the web (as long as you were logged in to OSF and part of the group). However, there is no search feature on OSF wiki and no automatically generated table of contents. Since starting, Quarto books came about, which come with a search feature and just look a little nicer while still basically being a collection markdown documents. Starting about a year ago, we began the process of transitioning all the materials on our OSF wiki into a Quarto book published at https://cct-datascience.github.io/group-procedures/.
If you’re unfamiliar, Quarto is “an open-source scientific and technical publishing system”—basically it allows you to combine markdown, code, and the output of executed code to produce a wide variety of formats. A Quarto book is a special type of website that is well suited for something like our group procedures. Unlike the OSF wiki, a Quarto book is searchable, and has a table of contents. However, it is not as easily editable on the web as the OSF wiki. I did my best to lower the barriers to editing the new book by 1) enabling an “edit this page” button on each page, 2) enabling a “report an issue” button, and 3) adding an “Editing this book” section with detailed instructions.
The “edit this page” and “report an issue” links on each page come from the repo-actions: yaml option in _quarto.yml. I enabled the “edit” and “issue” options. When you click the “edit this page” link, it takes you directly to the source code in GitHub and if you make a commit there, it’ll create a pull request for you that can be reviewed and merged. The final piece to making this work is that the book is rendered and published on GitHub pages using a GitHub action. That means any time there is a change in the source code, the live version of the book automatically updates.
The “report an issue” link on our book goes to a custom issue I created on GitHub specifically for suggesting edits to the book. You can create custom GitHub issues by adding a markdown file to .github/ISSUE_TEMPLATE/. For example, suggest_edit.md.
Finally, the “Editing this book” section has detailed instructions on how to clone the git repository to your laptop, open the project in RStudio, and preview the book locally on your laptop. This is useful for more substantial edits where taking advantage of the visual markdown editor might be helpful.
Because our book is now hosted on GitHub, it also allows easier tracking of the edit history of the book and allows us to periodically release versions that represent snapshots of our group policies and procedures in time.
This year, I plan on taking what I learned from this process to create a workshop and materials to enable lab groups to create their own lab handbooks as Quarto books. I’ve already been working on a template (still a work-in-progress!), and I’m really excited about sharing this with trainees and new PIs in a workshop once it is finished. In the meantime, if you’d like to adapt our group procedures book, feel free to do so (with credit) as it is released under a CC-BY license.