Your Second Source of Truth

Rate this content
Bookmark

FAQ

Rachel Neighbors is the documentation manager for React and React Native at Rilay, which is part of the React family.

According to Rachel Neighbors, the first source of truth in software documentation is the source code itself. However, since not everyone has the time to read through source code, the second source of truth is the documentation that explains how various components work together.

The React Native documentation was improved by adding more interactive examples, refresher materials on React, in-depth content on specialized topics, updates to high traffic component and API documentation, and engaging the community in updating the docs.

Updating the React Native documentation led to a 70% increase in thumbs-up metrics across the documentation pages, indicating improved user satisfaction and engagement.

The React Native team addressed the needs of developers from a mobile background by introducing context switchers and creating a React refresher to quickly introduce or reintroduce developers to React, ensuring the documentation was accessible to those unfamiliar with React.

Documentation is crucial in the React community as it helps scale knowledge, empowers the community to build and teach, and ensures the reliability of information. Notably, 86% of React developers learned using the documentation at reactjs.org.

Users can provide feedback on the new React documentation by visiting beta.reactjs.org, where there are options to leave feedback directly on the site.

Rachel Nabors
Rachel Nabors
8 min
22 Oct, 2021

Comments

Sign in or register to post your comment.

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: Tu Segunda Fuente de Verdad

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

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

Full Stack Documentation
JSNation 2022JSNation 2022
28 min
Full Stack Documentation
Top Content
The Talk discusses the shift to full-stack frameworks and the challenges of full-stack documentation. It highlights the power of interactive tutorials and the importance of user testing in software development. The Talk also introduces learn.svelte.dev, a platform for learning full-stack tools, and discusses the roadmap for SvelteKit and its documentation.
Gateway to React: The React.dev Story
React Summit US 2023React Summit US 2023
32 min
Gateway to React: The React.dev Story
Watch video: Gateway to React: The React.dev Story
The Talk discusses the journey of improving React and React Native documentation, including the addition of interactive code sandboxes and visual content. The focus was on creating a more accessible and engaging learning experience for developers. The Talk also emphasizes the importance of building a human API through well-designed documentation. It provides tips for building effective documentation sites and highlights the benefits of contributing to open source projects. The potential impact of AI on React development is mentioned, with the recognition that human engineers are still essential.
Opensource Documentation—Tales from React and React Native
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
Documenting components with stories
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 for Library Authors: Harnessing the Power of TypeScript for DX
TypeScript Congress 2022TypeScript Congress 2022
25 min
TypeScript for Library Authors: Harnessing the Power of TypeScript for DX
TypeScript for library authors offers benefits for both internal and external use, improving code quality and providing accurate understanding of libraries. Documentation and examples should be in code to provide up-to-date information. Testing types alongside unit tests ensures accurate typing. Managing changes and exposing types requires careful versioning. Deep integration of types improves usability. Using a map in TypeScript allows for simpler implementation and customization. Leveraging types in libraries can generate code based on user access. TypeScript integration with Nuxt provides support and type declarations.
The Legendary Fountain of Truth: Componentize Your Documentation!
React Advanced Conference 2021React Advanced Conference 2021
24 min
The Legendary Fountain of Truth: Componentize Your Documentation!
Welcome to this session about documentation in a command-driven era. The Data Axis framework provides a comprehensive approach to documentation, covering different areas of the development process. Component-driven development and MDX syntax enable faster development, simpler maintenance, and better reusability. Embedding components in Markdown using MDX allows for more advanced and useful documentation creation. Tools like Storybook and Duxy with MDX support are recommended for documentation solutions. Embedding documentation directly within components and migrating to MDX offer a comprehensive documentation experience and open up new possibilities for embedding and improving documentation.