Gateway to React: The React.dev Story

I was up late last night ensuring that all these slides were in dark mode just for the planetarium. You're welcome. I want to make sure you can drink your coffee and your lattes in darkness and quiet. I know it's too early for this. It's too early. But I got you. I got you.

Anyway, hey there. I've done a lot of things in my long career, including you may not know this, way back in the day I was an award-winning cartoonist and I used to be like the cheerleader for the web animations API which is only just now launching things in Chrome. And now I'm of course leading developer education at Clerk. I love teaching people. I can't see you so we're going to have to do this by cheers. I'm going to get you into this today. I'm setting a number here. How many of y'all use Clerk? Give me a cheer if you use Clerk. That's pretty good. That's pretty good. How many of you use react.dev? I can hear that. Actually I'm getting actual numbers out of this. 50% for react.dev. I can hear that. Okay. Cool. Boop boop.

Now, before all this I used to work on as I mentioned the animations. I built cool stuff like this. That's not too bright. You're going to be fine for the rest of these slides. Now we fully calibrated the audience we can proceed. And I love to travel the world teaching people to code and make really neat interactive things.

And of course, in 2018, I really got into Vue, because the community felt so warm and inviting. And Sara Drasner was making great educational materials leading their docs charge. And at that time I had tried to learn React a couple of times, and it just didn't stick. I'd get a course and tell me if this was you at one point. You'd get the course, and you'd sit down, and you'd spend like two hours trying to go through setting up webpack. And then you'd have all these dependency issues, and it was really discouraging. And you'd be lucky if you made it to the end of it, and even luckier if you remembered what you learned. I heard this over and over from other folks.

But 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 were for React. It was a barricade that you had to cross to get into that kind of a role. But this was interesting, because even for – oh, yeah, I think we're having one of the first – there we go – technical difficulties of the day. All right. Even for experienced people, like with computer science degrees, they would say things like, oh, you know, I still have trouble understanding React from the information available to me. I know this because I interviewed them extensively. And I was thinking to myself, well, if React were as easy to learn as Vue and it felt as nice a place to be as that community, more people like me could get six-figure salaries, amassed intergenerational wealth, change the world, change the – that sounds like a really nice lever I could push. Now, can I get paid to do that, is the next question.

So I joined the React team in London in 2019, as a developer advocate, documentation engineer, hybrid. By the way, pro tip, if you're ever going into big tech, do not take hybrid roles, that's a startup thing, big tech tends to have these career ladders and they're hybrid. Somebody is eventually going to come over to you like the eye of Sauron and be like, you have to pick one of these roles, and you'll be like, OK, I did not sign up for that one. Just pro tip, big tech likes to have clearly defined roles. Anyway, I did decide to join specifically with this one goal in my mind, to democratize React education for the world. I know, that sounds really self aggrandizing when I say it out loud. I had good intentions. My friends were like, why are you joining? 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. I don't know how you spent yours, but it was kind of cozy core. And yeah, so we're going to talk about that today. But, when I arrived at Meta, they said, great, you're here.

But before you can go work on ReactJS.org, we want you to spend all this strata into work on React Native's documentation. I had the task of turning around the docs there. It had just been redesigned, really cool landing page with animations by Nat Ellis. And I was like, hmm. Well, it looks good, but the docs obviously aren't connecting. But I don't know anything about the React Native community. What are they like? What keeps them up at night? What's mobile development? What do they want? So, I interviewed them. I actually started talking with individual React Native community members. And I ran surveys, and I learned a lot of things.

People needed more refresher material on React. Our documentation said, hey, you like React? React Native is like React, but for mobile development. Good for you. People actually didn't know React a lot of the time. We needed more visual content, more in-depth content on specialized topics. And, of course, interactive code. This is one of the big requests that we had. Because I don't know about you, but it's a little bit difficult to get a mobile development environment spun up on the fly. And sometimes you're just troubleshooting something. And it would be nice to do that right there in the docs, rather than having to, you know, start up Xcode.

So, in my surveys, I learned some interesting things. 41% of React Native developers were coming from a mobile development background. They weren't coming from a React development background. And there was, like, a whole 10% that had no programming experience, period. So, 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. So, one of the first steps we did was we added literal context switchers to speak to each learner's personal experience. Android developers have a different mental model than web developers. Also added the React refresher, which is an immediate boot camp for here's how React works. Go. So, you don't have to go all the way to MDN to learn JavaScript, so then you can go to react.js.org, so then you can come to React Native stocks. Which, by the way, was the learning path for many mobile developers coming to React Native.

This made it a lot faster for them. And worked with our wonderful friends at Expo to add interactive code sandboxes on every page of our API docs, which were incomplete. But fix that, too. Because those API docs weren't built from source, they had to be hand-edited. I ran this wonderful documentation doc-a-thon with the community where everyone, we went through the code source together, and updated the API docs. Pretty cool. Not scalable, but cool. And brought in community experts as guest writers, we wrote our security docs, filled them out with beautiful colorful illustrations as well, which turned out to be quite popular. And finally, used the React-native.dev domain, which we had been sitting on for quite some time, to launch in July 23rd of 2020. So it was no longer github.io, slash, facebook, slash. Now we had an actual URL. It looks like somebody belongs here. So the fun thing was that all this work, it lifted React-native's documentation thumbs-up to thumbs-down ratio by 70%. This whole effort took about six months, and it was a community effort and I did it as well. It's pretty good. It's pretty good numbers, right? Yeah, it's pretty good.

So with that success, it was time to work on React. We didn't know it as react.dev in those days. We knew it as reactjs.org a long, long ago. Now, React's documentation has a huge responsibility. 86% of React developers surveyed started with our Docs. Of course, these were also people answering surveys on Twitter and through our Docs, so you know, they might be a little biased. But still, a lot of people are learning React first through the documentation. Those numbers have probably skewed a little bit more as people have been moving more and more towards YouTube.

But the effort actually kicked off May 27th, 2020. This is actually a photo from my Kurzgesagt Mindfulness Journal. It literally says like, I played Starcraft at work and kicked off the React Education Materials Reboot, and I got to talk to Amanda and Britney at work. That was cool. Things I'm grateful for. All right. It was the start of the pandemic. And like with React Native, I was like, I'm going to start with the community. I'm going to interview the community. I want to know what they want. What are they thinking about? I think a lot of people make assumptions about the community that 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. If I ran this survey again, I'd be surprised. It's important to always double tap what you think are truths about the people that you know and you work with.

Okay. What did they say? Well, the results were very similar to React Native. Could you please teach us� except of course with this one, could you please teach us function components first? Everything is classes. Classes all over. The function component documentation is like in three separate places. Please stop. Hooks reference.

Once again. Like where were dependencies? Well, that's a good question. You kind of have to know which secret door lever to pull to find it or memorize all the locations of the hooks mentions. The docs were reading more and more like code essays. They needed a significant information architecture overhaul. And of course there was a request for more visual content. And of course interactive code. People wanted to be able to play with the examples. They didn't want to have to build, you know, an entire developer environment and spin up a new repo.

All right. So this all started with a brainstorming session with Dan Abramoff. It was within the lockdown's guidance. This was totally legal. We managed to go during one of the breaks. We used postcards. There were lots of doodles. I still have these. I think they're really cool. One day they'll probably go in a museum. It might be a museum about Dan. We'll find out. And Dan and I tended to communicate in sketches. And because of that, I made a new friend during the pandemic, known as React head. So doodling was a very important part of my journey with React. I would doodle a concept and show it to the human being, like, did I get this right? Is this how this thing is working? This led to some pretty cool things, like this one weird visual notation I was working on for state management for React DevTools. Don't ask. It didn't go anywhere. But I started to doodle this little guy who was inspired by IKEA, my favorite furniture store ever, and it was sort of, like, what if we had, like, React communicating with us, without words, kind of visually explaining how to do these things. So this React head became my little co-presenter when I was using these notes to communicate what I'd learned from Dan. And eventually we ended up describing React as a waiter who was bringing people components from the kitchen, and you can see it sort of evolved to this more finished end illustration type.

And you can still see these in the docs. They were super fun.

Okay. We ended up with this huge spreadsheet of content. If you're ever wondering, like, why the docs take so long, it was like writing a new book. It was like writing a book from scratch about React. Because the team believed we had to take a completely new approach to teaching React. This wasn't just moving some stuff around with, like, React Native. 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. We went to beta, December 8th, 2020, so that the community could actually access this new information. It took a while, obviously. React Head made their debut. Yay! Good React Head. And Maggie Appleton actually built a diagramming system. I had drawn diagrams. You don't want to see them. They're undecipherable. But Maggie built this amazing diagramming system that really helps make sense of things. One of my favorite bits is that Sylvia Vargas helped with... We wanted to make sure that all the examples used international tone. No Star Wars references, because that's American pop culture. Is it React's job to export American pop culture to the rest of the world? No, leave that to Disney. So we came up with this laundry list of international things that all of humanity can celebrate. Like cuisine. Art. Cities. And, you know, just the things that are common human heritage.

And Sylvia was just this really cool person from the community, came in, took that list, ran with it. And that's why you've got these really cool examples that celebrate all kinds of great thinkers throughout human history.

Yeah, it's like going to school, while you're going to school for React. And of course code sandbox helped us with making these interactive sandboxes possible. These were the real game changer. Whereas previously learning React, getting from zero to hello world, would take like an hour of setup, and you better hope all the instructions and the tutorial were compatible with whatever system you were running with, whatever cruft your day job had you running. No. Here, all you had to care about was the syntax. And that's where the magic was for React, and that's what we wanted to share with people.

People learn by doing. On the job training, we all know that on the job training will beat a college degree in this line of work any day. But why is that? Why is it that just theoretical knowledge isn't as good as the knowledge that you get from having been in the field? It all boils down to spaced repetition. There's a great book called Make It Stick. You can read it if you want, but I'm going to TLDR it for the audience, because you're still drinking your coffees here. Basically the idea is quizzing. The reason your teachers in school quiz you all the time is because you being forced to recall and use knowledge over and over again makes those paths really bake in your mind. It makes those neurons fuse. So it becomes like a mental muscle that you can't stop using. The engineers I worked with at Meta, they could look at a pattern of code and just kind of guess what it was doing. Not with reading it, but just kind of seeing its shape, because they were doing that spaced repetition day in day out. How could we recreate that with documentation? Well, we were going to. We had these, we invested in building these editable examples that did let these people get started right there with the syntax in zero seconds. No environment setup. No dependencies to fight. Just you do this thing and that thing will happen. And that was a video and I should've hit the clicker button to make it run. It is running now. I had to reshoot this last night. Cut me a break. But anyway, anyway.

But these sandboxes let us ship something we called challenges. Now, challenges were inspired by React trainers online like Josh Comeau, who you're going to hear from later, who would do these cool things where you'd have a lesson you go through and a quiz at the end and you'd pass the quiz. You go on to the next lesson. But we didn't want to stop people from going to the next lesson because forcing people down a linear learning path on the Internet does not work. People come onto a page, they look for answers, they leave. You can't coerce them into any sort of a test. But, at the end of each lesson, there'd be this challenge of things that the React core team had noticed people were stumbling on. Questions that Dan had answered over and over on Twitter. But these challenges would actually give people the chance to solve those problems at the end of the lesson so that they could become acquainted with the pattern of the code.

OK, that sounds great, but how do we know if all of this is working, right? How do we know? Well, much like I like to say it, ask real people. Don't think, don't guess, don't stare at a metrics sheet and be like that number looks like it is going up. I'm assuming it's a good or a bad thing. Don't do that, don't do that. Just ask people. If you ask people, they tell you everything you want to know. In alpha testing, users, I would be like hello, fill out this survey before you get a chance to look at the new site. And then a week later, be like hi, you've looked at it. Now would you fill out this other survey? And people were three times more likely to recommend the new React documentation coming out of having used it than they were recommending the old documentation when they went in. That was pretty nice. That's theoretically like, OK, we can ship this, I guess. We were going to ship it anyway, but it's nice to know. So, March 16th, 2023, the docs were finally mission complete, all the tutorials were added, the API references were complete. You can remove the go look at the beta docs banner from the top of the old ReactJS site. By the way, it still exists if you want to learn about classes. It's still there. Don't worry. Don't worry, it will always be there, although it will not be updated. And boom, ship the new React.dev with a new, new shiny landing page. Which looks quite good in this planetarium, if I do say so myself. The docs shipped with over 600 interactive examples.

Feeling pretty good about that one. And the illustrations, the interactive sandboxes trialed in React native's documentation. They went on, they changed how we shipped React documentation. I really do want to give a shout out to the React native community for all their help. Because so many of the ideas we trialed there ended up getting baked into React's docs. These sorts of educational efforts always build on top of each other. We're always pushing as trainers and educators how to do things even better than the last generation did.

During that beta period, 8 million learners had access to these docs. I hope you're going to love both of them. But 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. How do we transfer knowledge from a core engineer's mind to an implementation developer's mind? There is 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.

I like to think of it like building a human raid, where I'm copying information from one person's mind into the other. You can get really creepy with this if you're a propaganda artist. I don't use my powers for evil, though. So I always remember one of Sarah Drasner's infamous quotes, that people who find bad docs are just going to bounce. They bounce from your community, they bounce from your product, they give up. Because that length, that journey from the inception of the tool, no matter how useful it is, was just too long. It was too hard for them to get that knowledge. So how do you build that API? I did want to give you some pro tips. I know we have some people who are maintaining great resources in the audience today. How do you build your own human API? This is the recommendations I'm going to give you if you're into this. Number one, you want to set up a site. Use your words. You can use a readme on Github, that's cool. Github isn't the most searchable or findable thing. You probably want to set up a site. So you're probably like, oh my God I'm going to build a custom site it's going to be amazing.

Stop right there. Do not. I think you can spend a lot of time building a site. We probably could have shipped the docs like six months earlier if we just used the old site. There were a lot of gains. But was it really the center point, like was the purpose to ship docs or to ship a site? 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 for some reason, just goo with something out of the box like Docusaurus or Starlight from Astro.

I used to think the React docs or the Stripe docs were the best docs in the world. So I know, I have to say, I tip my hat to the Astro team, they've got like 800 people working on docs in their community round the clock, and they have evolved how docs can be done, and you can get it all out of the box with their Starlight project. So shoutout to the Astro team and the Starlight team specifically. Fun here, React docs, people get asked this a lot. So what exactly was the React site and the React Native site built on? Well, React Native and Relay's documentation is built using DocuSource. But the React documentation is built on a custom Next.js site. We probably could have gotten the content out faster if we just stuck with the Gatsby build that we had earlier, but we wanted to see if we could have built something even more fast to iterate on from the backend, like for engineers to go and write documentation. So it came up with a slightly different flow. Your mileage may vary. Choose what you want.

Step number two, balance what you write. A lot of times when we're writing for an audience, we tend to go overboard. We launch code essays. When you're working on a product for the first time, when you're building something, you want to share and you want to share as much as you can. That's great to a point. But at some point, you want to get organized with your thoughts. You want to think about how you're sharing and what you're sharing. There's this great system called Diataxis. I'm not pronouncing it correctly. You can go look it up. Anyway, it's a systematic approach for documentation and authoring. It's popular.

It's popular. There are other models, like DITA from IBM, which is just overkill for anything you're working on, I assure you. This is probably the best for most of us.

Let me give you my way of thinking about it, which is like a food pyramid of content. You start with your API references, then you kind of explain how everything works with your conceptual overviews. You get tutorials that are like step-by-step walkthroughs. And then at the end, you've got your guides, which are kind of like the packet drawer of information. Go read about it. You'll be happy you did. You're going to spend more of your time focusing on what matters.

The important thing is, as long as you have your API references down pat and in place, your community can probably help you write the rest of that information. But if you don't give them a complete and correct API reference, they can't help you. So make sure that that is your number one priority. Automate what you can. Don't spend all your time writing. You can use something like JS doc to transform your comments into API references. You can make this real fast. There's like plugins for using this with DocuSource. Go for it.

It's invested in test-driven example code, by the way, in its documentation, and it remains one of the paragons of future-proof docs that I like to pull out. Tests and documentation go together like cheese and crackers, in my opinion. They forge a promise to users of deliciousness. No, I'm kidding. They form a promise to users that when they do a certain thing, they can expect certain results. That's how people feel when they're using your product. It's how they feel when they're learning your product, too.

And lastly, take an interest in something called content design. This is a lovely little field of expertise usually associated with user experience and marketing. But there's some great books about documentation. Docs for Developers is a quick intro to writing better, but in terms of content design, Everyday Information Architecture by Lisa Maria Marquis, it's a really good book for how to think about how you're organizing your content to be understood by other people.

And if you are really thinking, man, I've got to build a team, Leading Content Design is a great book as well by Rachel McDonald. And lastly, join a community, make some friends. There's a community out there called Write The Docs, writethedocs.org. They're a great group of people who have solved many of these problems many times over and they can give you good advice and pointers if you are, if this is your job.

All right, I think that's it for me today. I just wanted to say, I will see you at the Barcade tonight. Yes, there is a Nintendo Switch, but more importantly, the clerk has brought these fabulous fanny packs. Woohoo! It's nice. Yeah. So, it's obviously a very fashionable event here because there are shirts, myth edition shirts, fancy fanny packs, all the swag that your heart desires for the New York runway. So thank you very much. I will see you at the Barcade tonight and I will not be pwning everybody on Pac-Man. I have to give you your chance to win a Nintendo Switch. I already have one. Thank you so much. I hope you love React.dev. It was a labor of love by so many people. Truly grateful for all the effort that everyone has put in to teaching the world to think and react over the years.

What's your preferred race in StarCraft? Zerk. Oh, all right. Very cool. Nice. I'm not a StarCraft person, but is that a Toy Story type reference to do? They're really gross. Oh. Okay. They're gross, and they require high clicks per minute to use properly. They're for micromanagers, essentially. Okay. And you have to... They make you move faster, that's why I like them, because it was a challenge to move faster, plan less, move faster.

Yeah. That's really cool. Awesome. Okay. That was a great question. Thank you, whoever asked that. You have a good StarCraft fan out in the audience. Why is React Native documentation separated from the React documentation, even though the web and native share the same core package? That is actually a really good question. And I would say that it comes down to, at the time, when I was there, and this is no longer the case, the React Native and the React teams were very split, so the documentation kind of reflected the split in thinking, and the split in team organization, as well as, you know, we don't always hear from React Native and React in the same breath. The two communities are very different. React Native community is cross-platform mobile development community, and the React community tends to be more web-based, but it's true that the same core package does drive both of them. It's just the community doesn't look that way. But now the two teams are one React team. One React, by the way, is going to be my next slogan that I'm going to use at these conferences one world, one React. Xbox one. React one. Yeah. So, maybe that'll change.

Yeah, absolutely. So, this is a bit open-ended, oh, sorry, not the one I wanted, hold on, hold on, hold on, that's the one I want. Okay, so the question is where to start from? And I would say maybe broaden it out to, is there someone who would want to get into doing article writing or documentation? Like, how do you get started? I was like, how do you get started with React? I just told you. Well, yeah, okay. Go to react.dev if you want to get started with React, but it's a good thing for your career to write. How do you get started teaching? Yeah, exactly. How do you get started documenting? Well, honestly the best place to start, in my opinion, is to find something you love. We all have something we love, like a tool we can't stop using or an open source project we adore. And think about the one that's not the most popular. Think about someone who's not the prettiest girl in the room. And you'll find that those people probably would really love if you came and donated a little time to write a tutorial or to write some blog posts. But I always say, blog posts are great. Writing on your own platform is great. It's great for increasing your personal brand, which everyone is doing, which is capitalist commodification of self, which I don't agree with. But, you know, thank you to whoever that... Go, capitalism of self. But I will say, if you go and you work with the official, like the repo owners, and you say, hey, I love your project, I would love to spruce up your readme file, launch a small docusource site with some of the tutorials I've been thinking about, they're usually really excited for you to do that. Once you get those green squares on GitHub. Yeah. And something to put on your resume. Exactly. Another big skill, communication. Oh, that is important, too. Everyone, like right now, it's kind of a scary time in the development world. Yeah, that's true. If you wanna get experience that you can put down on your resume while you're still relatively new in the community, open source work is the way to do it. You get to work with somebody, no paycheck usually, but they can vouch for you in an employment situation. All right. So, what was the most difficult React concept to teach? Oh, man. I feel like that's a tricky question.

Use-effect? Yeah. It's use-effect. It's use-effect. It's always use-effect. It's like, how do you teach an escape patch? Yeah, yeah. I think my exact response at one point was, why don't we just give people a compiler? Oh, that's an idea. Yeah. I forgot about that. There is a small compiler coming, so I'm excited about that. It's like, oh, sweet. Less to teach. Right. React, forget, by the way.

Alright. So, actually, segueing into the next topic, how does the possible chance of AI affect the React developer? Man. How does AI affect all of us? Everything. I feel like that is a very existential question. Well, you won't have to think too much about remembering all your dependencies in the future, because React is 100% understandable by robots, so the good news is it'll probably make our lives easier. Because we won't have to remember all the foot guns and all the things. Copilot will remind us. Exactly. I actually think that AI will really help React developers be more efficient. I think we're still a long way off from a point where generative content can replace an engineer, but it will certainly be, I think, a valuable tool for helping us compose UI as opposed to, I think, our very brute-force methodology that we have to do today. All right. Thank you so much, Rachel.