So you (don’t) think you can review a package

Contributing to an open-source community without contributing code is an oft-vaunted idea that can seem nebulous. Luckily, putting vague ideas into action is one of the strengths of the rOpenSci Community, and their package onboarding system offers a chance to do just that.

This was my first time reviewing a package, and, as with so many things in life, I went into it worried that I’d somehow ruin the package-reviewing process— not just the package itself, but the actual onboarding infrastructure…maybe even rOpenSci on the whole.

Barring the destruction of someone else’s hard work and/or an entire organization, I was fairly confident that I’d have little to offer in the way of useful advice. What if I have absolutely nothing to say other than, yes, this is, in fact, a package?!

So, step one (for me) was: confess my inadequacies and seek advice. It turns out that much of the advice vis-à-vis how to review a package is baked right into the documents. The reviewer template is a great trail map, the utility of which is fleshed out in the rOpenSci Package Reviewing Guide. Giving these a thorough read, and perusing a recommended review or two (links in the reviewing guide) will probably have you raring to go. But, if you’re feeling particularly neurotic (as I almost always am), the rOpenSci onboarding editors and larger community are endless founts of wisdom and resources.

🔗 visdat 📦👀

I knew nothing about Nicholas Tierney’s visdat package prior to receiving my invitation to review it. So the first (coding-y) thing I did was play around with it in the same way I do for other cool R packages I encounter. This is a totally unstructured mish-mash of running examples, putting my own data in, and seeing what happens. In addition to being amusing, it’s a good way to sort of “ground-truth” the package’s mission, and make sure there isn’t some super helpful feature that’s going unsung.

If you’re not familiar with visdat, it “provides a quick way for the user to visually examine the structure of their data set, and, more specifically, where and what kinds of data are missing.”¹ With early-stage EDA (exploratory data analysis), you’re really trying to get a feel of your data. So, knowing that I couldn’t be much help in the “here’s how you could make this faster with C++” department, I decided to fully embrace my role as “naïve user”.²

🔗 Questions I kept in mind as myself resident naïf:

• What did I think this thing would do? Did it do it?
• What are things that scare me off?

The latter question is key, and, while I don’t have data to back this up, can be a sort of “silent” usability failure when left unexamined. Someone who tinkers with a package, but finds it confusing doesn’t necessarily stop to give feedback. There’s also a pseudo curse-of-knowledge component. While messages and warnings are easily parsed, suppressed, dealt with, and/or dismissed by the veteran R user/programmer, unexpected, brightly-coloured text can easily scream Oh my gosh you broke it all!! to those with less experience.

🔗 Myriad lessons learned 💡

I can’t speak for Nick per the utility or lack thereof of my review (you can see his take here, but I can vouch for the package-reviewing experience as a means of methodically inspecting the innards of an R package. Methodical is really the operative word here. Though “read the docs,” or “look at the code” sounds straight-forward enough, it’s not always easy to coax oneself into going through the task piece-by-piece without an end goal in mind. While a desire to contribute to open-source software is noble enough (and is how I personaly ended up involved in this process– with some help/coaxing from Noam Ross), it’s also an abstraction that can leave one feeling overwhelmed, and not knowing where to begin.³

There are also self-serving bonus points that one simply can’t avoid, should you go the rOpenSci-package-reviewing route– especially if package development is new to you.⁴ Heck, the package reviewing guide alone was illuminating.

Furthermore, the wise-sage 🦉 rOpenSci onboarding editors⁵ are excellent matchmakers, and ensure that you’re actually reviewing a package authored by someone who wants their package to be reviewed. This sounds simple enough, but it’s a comforting thought to know that your feedback isn’t totally unsolicited.