1. Introduction to Documentation as a Source of Truth
I'm Rachel Neighbors, documentation manager for React and React Native. Today, I'll talk about documentation as your second source of truth and a project with React Native in 2019. Your first source of truth is your source code, but you'll need a second source of truth. The next best thing is your documentation that shows how all these different pieces work together and how people can implement them and work with them and build things.
♪ Okay, so a little awkward. I'm totally crashing these lightning talks and I've disrupted the chain of events that should play out. I don't even know how long I'm supposed to be talking. So, if I go on too long, and I am, in my old age, telling far too many stories, you are welcome to just start shouting, we're very bored, please get off the stage now. I will do that. But I will try not to take up too darn much space today.
Hi there. I'm Rachel Neighbors, documentation manager for React and React Native, and Rilay, who is also a part of the React family. Although, you may not have heard of it, you know, at GraphQL. Anyway, that's for a future talk. And today, I've come to chat with you a little bit about something that, well, a couple of things. First off, I don't know if you noticed, but we just kinda had a whole year of dead air. I mean, what was that? My concept of time has completely gone out the door, hence why I might run a little long. But there was actually something I wanted to share with you before the pandemic wiped out all the talks and all the conferences. And that is why I'm here to talk with you today about documentation as your second source of truth. And there was a little project back in 2019 with React Native, and I want to tell you a little bit about it. But first, docs, your first source of truth is your source, of course. I mean, your first source is your source, of course, of course. Your first source of truth is your source, code, of course. But very few code bases can be read through in one hour. I remember the era of jQuery, where you could learn JavaScript and jQuery by literally reading the jQuery source code, if only we were so lucky today. So your first source of truth might be your source code, but you're gonna need a second source of truth. The next best thing is your documentation that shows how all these different pieces work together and how people can implement them and work with them and build things, et cetera, because otherwise, you don't have time to read all the source. That was not the right animation. Oh well, carry on. We're getting back into the groove here. I'm surprised that the MCs have still got it, even though they've been off the air for like a year. Dang. Let's see if I've still got some, too. So when I first joined the React team, I had the task of taking React Native, React Natives and a lot of React Native folks here today and its documentation site and making the docs rock even more.
2. Improving React Native Documentation
It was a fun project. User testing revealed the need for more refresher material on React, as well as more visual content and interactive code examples. We also learned about our audience, including their background and the importance of providing context switchers. We updated the documentation with interactive examples, engaged the community, and saw a significant increase in positive feedback. Good documentation is crucial for developers to excel and teach others. React.js has invested in its documentation since day one and has been instrumental in introducing many developers to UI development.
It was a fun project. User testing, I used to be a UXer back in the day, so I start all the projects I get assigned with like, let's talk to real people. And these conversations revealed that we needed more refresher material on React. Learners wanted more visual content. We lacked in depth content on some specific specialized topics, our high traffic component and API documentation needed a little update and people kept saying we want more interactive code. When can I run these examples? I'm not gonna set up an Android SDK, I'm an iOS developer, come on.
We also learned a little bit more about our audience and things we didn't know before. For instance, 41% of React native developers, they come from a mobile background. They didn't have any background in anything before they came or even web. These were very interesting people to talk with. And it also made us realize that, you know, probably should build in things like literal context switchers to speak to people from different backgrounds. Before we were just like, you probably know React, here's React for your mobile device. Which was cool except for people who are already developing for mobile and did not know what React was. So, NICE took care of that. We added these really cool interactive examples everywhere to get people up and running. React Refresher to introduce them to, reintroduce folks to React really quickly, which kind of inspired a future project we'll get to in a moment. And because the docs, well, they weren't automatically generated, that meant driving an entire community drive to update the documentation, which was a lot of fun because people really want to get engaged in their favorite project. But sometimes these projects are so far matured, there's no more low-hanging fruit, but there's still a way to participate in contributing to documentation. So we got everything back up to date. We brought in some experts as guest writers to patch up places where we needed some deep dives, added colorful illustrations that turned out to be very popular. And since rebooting React Native's documentation with the new content, we saw a 70% increase in thumbs-up metrics across the board on the page. That was really nice. It felt great.
So bad documentation can lead to bad developer experiences. It makes it hard for devs to get from good to great. And it makes it even harder for them to teach others, to spread the word about the thing that they love and that they've found. For instance, big communities need great docs. 86% of React developers, they've learned using the documentation at reactjs.org. That's kind of incredible. React.js has been investing in its documentation since day one, and people often say that the docs were where they first got into UI development in the first place.
3. The Power of Documentation
With the power of documentation, you can empower your community to build an ecosystem of reliable content. We've learned from React Native and the React community and put those lessons into action. Check out the latest iteration of the React documentation at beta.reactjs.org and give us your feedback.
So, you'd think, well, with that kind of power, you should spend a lot of time on your documentation, investing in your second source of truth to empower your community to build out an entire ecosystem of reliable, up-to-date content to teach each other, to dive deep, to build on top of what you've made, and to trust that what they're teaching is true and correct and something they can build a career or a community or a training course or a bootcamp off of.
That's scaling knowledge. And we're putting these lessons from before the pandemic, the things that we have learned from React Native and from the React community and what worked with the React.js docs, we've been putting them to action over the past, well, since the before times. And today, we want to share with you a little sneak peek of what we've been working on. This is super, super beta, but if you go to beta.reactjs.org, you can see the latest iteration of the React documentation. We'd love to know what you think about it. There's places on the site for you to leave feedback, and we hope to hear from you. If you like it, that's awesome. If you don't like it, tell us why. We're waiting for your feedback.
