smoores.dev

The Oak Team, the engineering team responsible for building and maintaining The New York Times' collaborative rich text editor, just had the most engaging, fulfilling sprint that I've experienced since I joined the team in 2019. We collaborated, supported each other, and learned new things. And we didn't push a single commit. Instead, every engineer on the team spent two weeks learning about how the core technologies we use every day really work, so that we could engage with them more deeply, and hopefully solve some long-standing problems we face while developing Oak!

What we sketched out became “Build Your Own”. “Build Your Own” is a five-part syllabus that breaks down React, ProseMirror, and Redux, and walks through how to build them back up from scratch. Let's talk about what it is and why we need it!

What Oak is made of

Before we talk about the learning sprint itself, some context. For quite a while now, the primary UI rendering library at The Times has been React. Since Oak is a WYSIWYG text editor, it shares React component code with our reader-facing website at nytimes.com. That way, when changes are made to how articles look on our website, our newsroom can also see those changes while the articles are being written! Oak also relies on ProseMirror, a library for building rich text editors. These two technologies, React and ProseMirror, introduce an interesting tension: they both want to have complete ownership over the DOM they're responsible for, and in many places they're responsible for the same DOM! Mediating this tension is one of the Oak team's primary technical challenges, especially when working on features that involve decorating the editor, like spellcheck.

Taking a step back

Thinking about challenges like this is one of my favorite aspects of my job as a tech lead. As I thought about this tension in particular, I began to see what made it murkier than many of our team's other technical challenges: we don't usually expect this knowledge from engineers that build applications. Most of the time, it's possible to treat libraries like ProseMirror and React as abstractions. It's almost always enough to just understand how to use our tools, and we leave understanding how they're built—and why—to the domain experts. But the fraught relationship between React and ProseMirror within the Oak codebase has given rise to frustrating and resilient bugs over the 5 years that we've been building it. Simply knowing how to use our tools was not enough.

This is how we ended up developing our learning sprint. To deviate from this standard mode of operation, our team had to think carefully about how to ensure that everyone was prepared to take on this work. We had to build a solid, shared foundation so that we weren't leaving anyone behind, and so that we could make the most of our collaboration as a team. This, I realized, was the real challenge: increasing our base level understanding of how React, ProseMirror, and Redux are actually implemented, so that every engineer on the team can engage thoughtfully in solving the problems that arise when these libraries are in conflict.

Build Your Own

What we sketched out became “Build Your Own”. “Build Your Own” is a five-part syllabus that breaks down React, ProseMirror, and Redux, and walks through how to build them back up from scratch. It's based on (and includes) the absolutely wonderful “Build your own React” tutorial from Rodrigo Pombo. Inspired by that tutorial, we wrote similar walkthroughs for building Redux and the ProseMirror EditorView component as well. Finally, to ensure that everyone felt comfortable with the terminology and fundamentals of using the library, we built quick refresher courses on the basics of React and ProseMirror.

Since the primary goal of this project was to ensure that everyone had the same foundational knowledge of these three technologies before embarking on projects to improve how we use them, it was crucial that the actual learning process was flexible enough to accommodate the different learning styles across our team. We made space for learning through dialogue, via the synchronous Slack Huddle, through reading, via the tutorials, and through experimentation, and via the Glitch projects we created for each course. We also incorporated feedback as we went, updating the courses and our processes to ensure they were as useful as possible.

We went through this learning sprint as a team in May of 2022. We've since used our shared knowledge to reimagine the way we integrate React, ProseMirror, and Redux in the Oak collaborative text editor. Every engineer on the team has been able to contribute to the project, including the two engineers who joined the team since we first wrote the course. Together we wrote forty-five tickets, and less than two months after the first one was opened, the refactor was live in production. We were able to build a new integration layer between React and ProseMirror that utilizes a deep understanding of ProseMirror NodeViews and React render phases, layout effects, contexts, and portals to create a clean, bug-free system that will hopefully serve us for the rest of Oak's life. Keep an eye out, because we're hoping to open source and release this new ProseMirror React integration library some time in 2023!

Overall, the learning sprint was a blast, and, I think, a fairly resounding success. The change was noticeable and instant: our team was much more able to engage with challenging conversations about each of these technologies. And folks had a great time, too!

Some testimonials from engineers on the Oak team about our learning sprint:

I loved that our Oak learning sprint accommodated the many learning and working styles on our team, with options to work asynchronously or together in a Slack hHuddle and flexibility for every engineer's personal pace through the tutorials. The work we do at the Times is never-ending, which just made it that much more meaningful that as a team, we were willing to take a week off from our normal sprint work to make sure we all understand what is going on behind the scenes in the tools we use every day. I know that when we start to tackle our H2 work, the learning sprint will continue to help us.

- Nozlee Samadzadeh

The Prosemirror-React learning week was extremely valuable to me as a mid-level engineer in that it forced me to examine the building blocks of the two main libraries we use to build Oak. Doing so allowed me to make sense of the patterns we use in our code, and the vocabulary to debug more effectively. Re-assembling Prosemirror-view and React demystified their mechanics and made me feel more empowered in leveraging their features.

- Anna Bialas