Rachel Nabors on Revamping React’s Documentation

React programmer and trainer Rachel Nabors noticed something while a beginning programmer: The six-figure jobs required React.

“When I was looking for a job, I noticed that most six figure salaries required you to learn React. They weren’t for Vue, they weren’t for Ember, they weren’t for the things that I saw the women in my coding community gravitating towards,” they said Monday during the React Summit US keynote. “It was a barricade that you had to cross to get into that kind of a role.”

The problem was Nabors struggled to understand React from the information available — and they noticed others did as well. So they joined Meta with a plan to democratize React education.

“My friends were like, ‘Why are you joining Meta?’ And I was like because I want to change the world in a good way. So I spent the pandemic building new React docs with the awesome React team and community,” they said.

Meta put Nabors to work on Reactjs.org’s React Native documentation. React Native is a framework for building cross-platform mobile applications. The site had been given a redesign, but the documentation was still disjointed.

But Nabors, who is also a web animations expert, didn’t just study the documents. Nabors and the React Native team overhauled the documentation to create a developer-friendly learning experience.

Get to Know the Community

“We needed more visual content, more in-depth content on specialized topics, and of course, interactive code,” Nabors told the audience.

But rather than dive in headfirst, Nabors first talked with individual React Native community members through one-on-one discussions and surveys. It turned out, 41% of React Native developers were coming from a mobile development background rather than a React background. Another 10% had no programming experience at all. React Native, for many, was the learning path to React — not the other way around.

“We were making a lot of assumptions previously about the kind of people who were trying to learn React Native, and the backgrounds that they had,” she said. “So one of the first steps we did was, we added literal context switchers to speak to each learner’s personal experience.”

The team brought in Expo to add interactive code sandboxes on every page of its API documents — which were incomplete, so that had to be fixed as well. They brought in community experts, guest writers to write the security documents, and then filled them with “beautiful, colorful illustration as well, which turned out to be quite popular,” Nabors said.

Finally, it was all deployed using the ReactNative.dev domain, which Meta already owned, to launch six months later on July 23, 2020.

“The fun thing was all this work, it lifted React Native’s documentation thumbs up or thumbs down ratio by 70%,” they said.

React Head Is Born

React documentation came next — and that was a huge responsibility, said Nabors, since 86% of React developers start with Meta’s documentation to learn the UI framework. That effort kicked off on May 27, 2020. Again, Nabors started by interviewing React community members to learn more about what they thought about.

“A lot of people make assumptions about the community — we think we grow up in it, we think we know it, but it’s changing constantly, even how people learn today is different from how they learned in 2020,” Nabors said.

Community members wanted resources to learn fiction components, hook references, and dependencies.

“It needed a significant information architecture overhaul; and of course, there was a request for more visual content and […] interactive code,” she said.

Nabors had a brainstorming session with Dan Abramov, where they used doodles on postcards to communicate in sketches their ideas. And that’s how Nabors came to create the popular React figure, React Head.

“I started to doodle this little guy who was inspired by IKEA, my favorite furniture store ever, and it’s sort of like what if we had React communicating with us without words, visually explaining how to do these things,” they said. “This React head became my little co-presenter, when I was using these notes to communicate what I’d learned from Dan.”

If it sounds like a walk in the park, it wasn’t. They had a huge spreadsheet of content that had to be reviewed and corrected. It was, Nabors said, like writing a book from scratch because the team had to take a completely new approach to teaching React.

“This wasn’t just moving some stuff around like with React Native. This was ‘We are burning the docs to the ground, we’re starting afresh.’ It was like writing a book, an interactive book, my favorite kind of book,” they said.

Interactive Sandboxes Simplify the Learning of React

It was the interactive sandboxes that were a game changer for the documentation, however.

“Whereas previously, learning React — getting from zero to ‘Hello World’ — would take an hour of setup and you better hope all the instructions and tutorials were compatible with whatever system you’re running. Here, all you had to care about was the syntax,” Nabors said. “That’s where the magic was for React and that’s what we wanted to share with people.”

They based the documentation on an education concept called spaced repetition, which holds that quizzing frequently forces one to recall and use knowledge over and over again, creating neural pathways until the knowledge becomes almost like muscle memory. The engineers at Meta could look at a pattern of code and guess what it was doing just seeing its shape, because they were doing the spaced repetition day in and day out. The question was, how could that process be recreated with documentation?

The documentation team invested in building editable examples that let developers start with the syntax without requiring an environmental setup or managing dependencies, or any of the complexities required when setting up React. These sandboxes let the team ship challenges, which were inspired by React online trainer and fellow React Summit speaker Josh Comeau. The coder can move on to the next lesson when they pass the quiz or scenario.

The team knew it couldn’t force users to take the challenge, so they formulated the challenges around common questions that stumped users and that Abramov had repeatedly been asked to explain on Twitter (X).

“These challenges would actually give people the chance to solve those problems at the end of the lesson so that they could come acquainted with a pattern of the code,” Nabors said.

In a test run, the team found that people were three times more likely to recommend the new React documentation than the old documentation. The new documentation shipped on March 16, 2023, with more than 600 interactive examples, illustrations and interactive sandboxes. It changed how Meta shipped React documentation, Nabors added.

“I like to think about these documentations not as written words, not as dry docs, or a user manual — I like to think of them as a human API,” Nabors said. “There’s a long journey from the person who builds the tool to the person who wields the tool. And the shorter we make that journey, the faster we get to build the future.”

3 Steps to Create Better Documentation

First, Nabors suggested that developers, in building their own human API for knowledge transfer, think hard about purpose and what’s needed, rather than just launching a new custom site right off the bat.

“Be clear, you’re trying to ship knowledge, it’s easy to set up a great site today — unless you have a real reason you need to build a custom site,” they advised. “Just go with something out of the box.” Starlight from Astro is a good resource for that, but they also recommended looking at its documentation, which involves more than 800 people working on the docs in their community.

The React Native site and relays documentation are built using Docky Source, which is open source. The React documentation is built on a custom Next.js site, although Nabors said they probably could have gotten more content out faster if they had just stuck with an earlier Gatsby build.

Second, Nabors advised that developers should balance what they write, meaning coders shouldn’t be writing coding essays as documentation. Nabors thinks of documentation as a food pyramid of content, that starts at the foundation with the API references, then goes up to conceptual overviews, then tutorials that are step-by-step walkthroughs. At the top of the pyramid, there are guides, “which are kind of like the packet drawer of information.”

Test and documentation go together like cheese and crackers, Nabors said.

“Rust invested in test-driven example code […] in its documentation, and it remains one of the paragons of future proof docs that I like to pull out,” Nabors said.

Finally, Nabor recommended developers invest in learning about content design, which is usually associated with user experience and marketing. However, there are some books that focus on content design with a developer in mind, such as Lisa Maria Marquis’ Everyday Information Architecture or Rachel McConnell’s Leading Content Design.

Editor’s Note: This piece was updated to reflect the correct last name of Dan Abramov on Nov. 27, 2023.