Your Second Source of Truth

Rate this content
8 min
22 Oct, 2021

Video Summary and Transcription

Rachel Neighbors discusses the importance of documentation as a second source of truth for developers. She shares insights from improving the React Native documentation, including the need for refresher material, visual content, and interactive examples. Neighbors emphasizes the power of documentation in empowering communities to build reliable content and highlights the React documentation as a successful example. She invites feedback on the latest iteration of the React documentation.

Available in Español

1. Introduction to Documentation as a Source of Truth

Short description:

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

Short description:

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 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

Short description:

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 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, 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.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

JSNation 2022JSNation 2022
28 min
Full Stack Documentation
Top Content
Interactive web-based tutorials have become a staple of front end frameworks, and it's easy to see why — developers love being able to try out new tools without the hassle of installing packages or cloning repos.But in the age of full stack meta-frameworks like Next, Remix and SvelteKit, these tutorials only go so far. In this talk, we'll look at how we on the Svelte team are using cutting edge web technology to rethink how we teach each other the tools of our trade.
React Summit US 2023React Summit US 2023
32 min
Gateway to React: The Story
A behind the scenes look at the design and development of the all-new React docs at The new launched this year introducing new methodologies like challenges and interactive sandboxes and subtle inclusivity features, like "international tone" and culturally agnostic examples. Not only have the new docs changed how people learn React, they've inspired how we think about developer education as a community. In this talk, you will learn how the React team and some ambitious community members made the "React docs rock" for a generation of front end developers and how these new patterns and established techniques can be applied in your favorite projects.
React Finland 2021React Finland 2021
27 min
Opensource Documentation—Tales from React and React Native
Documentation is often your community's first point of contact with your project and their daily companion at work. So why is documentation the last thing that gets done, and how can we do it better? This talk shares how important documentation is for React and React Native and how you can invest in or contribute to making your favourite project's docs to build a thriving community
React Finland 2021React Finland 2021
18 min
Documenting components with stories
Most documentation systems focus on text content of one form or another: WYSIWYG editors, markdown, code comments, and so forth. Storybook, the industry-standard component workshop, takes a very different approach, focusing instead on component examples, or stories.
In this demo, I will introduce an open format called Component Story Format (CSF).
I will show how CSF can be used used to create interactive docs in Storybook, including auto-generated DocsPage and freeform MDX documentation. Storybook Docs is a convenient way to build a living production design system.
I will then show how CSF stories can be used create novel forms of documentation, such as multiplayer collaborative docs, interactive design prototypes, and even behavioral documentation via tests.
Finally, I will present the current status and outline a roadmap of improvements that are on their way in the coming months.
TypeScript Congress 2022TypeScript Congress 2022
25 min
TypeScript for Library Authors: Harnessing the Power of TypeScript for DX
Using real-life open-source examples, we'll explore the power of TypeScript to improve your users' experience. We'll cover best practices for library authors, as well as tips and tricks for how to take a library to the next level. This talk will cover: 
- how to leverage the type inference to provide help to your users; - using types to reduce the need and complexity of your documentation - for example, using function overloads, string literal types, and helper (no-op) functions; - setting up testing to ensure your library works (and your types do too!) with tools like tsd and expect-type; - treating types as an API and reducing breaking changes whilst shipping enhancements; - I'd draw on my experience with libraries like nuxt3, sanity-typed-queries and typed-vuex and show what we managed to do and what I'd do differently in future. 

React Advanced Conference 2021React Advanced Conference 2021
24 min
The Legendary Fountain of Truth: Componentize Your Documentation!
"In Space, No One Can Hear You Scream." The same goes for your super-brand-new-revolutionary project: Documentation is the key to get people speaking about it.Building well-fitted documentation can be tricky. Having it updated each time you release a new feature had to be a challenging part of your adventure. We tried many things to prevent the gap between doc and code: code-generated documentation, live examples a-la-Storybook, REPL...It's time for a new era of documentation where people-oriented content lives along with code examples: this talk will guide you from Documentation Best Practices – covered from years of FOSS collaborative documentation – to the new fancy world of Components in Markdown: MDX, MDJS, MD Vite, and all.Let's build shiny documentation for brilliant people!