The #1 Notebook Collaboration Tool

Learn more

Introducing JDoc: Team Conversation on Jupyter Notebooks

3 minute read

At ReviewNB, we already support Jupyter notebook visual diffs & reviews for GitHub commits/ pull requests.

Today we’re releasing JDoc, a simple way for teams to review notebooks on GitHub. You can open a notebook in your repository & start discussion under any notebook cell. Teammates watching this repository or participating in the conversation will be notified (via email) so they can chime-in and move the conversation forward. This workflow would be very useful for Data Science / ML teams to review each other’s work, ask clarifying questions & provide feedback directly on the notebook cell.

Why the new feature?

We offer notebook review functionality on a pull request which works great in many cases but falls short in some.

  • Sometimes you don’t care about notebook diffs. E.g. I commited a new notebook with some ad-hoc analysis & would like to have someone on my team review it. Creating a pull request for the sake of review is a bit superfluous since there’s no diff for this file (newly added notebook) & there’s no merge-to-master workflow post review (ad-hoc analysis).

  • Not every notebook user is proficient with Git/GitHub. Asking them to create feature branches and open pull requests can be a bit too much. With JDoc, the author just needs to commit the notebook to GitHub and it’s available for review.

  • Sometimes you want to see all past discussion on a particular notebook & navigate to different version of the file. JDoc makes this easy with its notebook centric approach to peer reviews & version control.

How does it work?

  • When you open a repository on ReviewNB, you can now see the new NOTEBOOKS tab


  • You can open a notebook & start conversation on any notebook cell

  • Teammates watching this repository or participating in the conversation will get a new comment notification on email. Of course they can unsubscribe from email notifications if they so wish.

  • Teammates can reply / resolve / start a new conversation or just skim through the comments. There’s also a CHANGES tab which shows version history of this notebook.

Important things to note

  • With pull request reviews, all comments you write on ReviewNB are directly posted to corresponding PR on GitHub. With JDoc, all comments you write are stored with ReviewNB. This is because GitHub does not offer any way to post comments directly on a file (GitHub comments are permitted only on commits/PRs). Of course, your comments are safe with ReviewNB & repository admins can request machine readable export of all the comments on their repo.

  • Currently, if you change notebook name/path in the repository then it’ll be treated as a new file & you won’t see old conversations on it. This is because it’s not easy to detect file renames with raw git data. In future, we’ll provide a UI to specify renames which will then port over the comments.

  • Since JDoc is like Google Docs for Jupyter, a lot of conversations can accrue over a lifetime of a notebook. It’d be wise to actively resolve/delete old conversations so as to keep the document clean & tidy.

Conclusion

JDoc lowers the entry barrier for peer reviews of Jupyter Notebooks. And in some cases they make more sense than a pull request review e.g. you want to review a newly added notebook or you just want to put the final notebook version for review & don’t care about incremental updates to get there.

Pull Requests reviews are still great to see visual diffs & they act as a fantastic container for the discussion. There’s also an engineering rigour to the PR process as the final outcome is merge-to-master.

I hope you can combine the power of PR reviews & flexibility of JDoc to reach a balance suitable for your team.

Happy Hacking!

You May Also Enjoy