Elevate Your Documentation: A Review of React Docs

Get inspired by React Docs to enhance your project's documentation

This year, one of the books I selected for reading was Docs For Developers. It’s a great, entertaining book that teaches how to build documentation for developers. It’s mostly about user-facing documentation, where other developers are on the receiving end. It’s a great story about building an API that is well-documented, so the product is enjoyable to use.

It taught me what to focus on in documentation, how to improve documentation quality, and how important feedback is. It also has valuable lessons for documenting software projects, so even if you are not building a public API but rather writing documentation for your software project, it’s still a book worth reading.

Armed with new knowledge, I read the React docs. I was surprised by how good they were. Even as a seasoned developer using React daily, I learned a lot from them.

In this blog post, I will share what I learned from the Docs for Developers book and React's user-facing documentation.

Illustrations

After learning a lot and trying different resources, I know that text content has no advantage over video, audio, or illustrated content. While people think that everyone is different and prefers their own learning style, the truth is that a mix of these is the most effective way to learn.

The Docs for Developers book proves the value of using visual content in documentation. The research shared in the book concludes that users who followed instructions with illustrations were 323% more successful at completing the instructions than those without illustrations.¹

What I like about the React docs is that they’re mostly text but they also include illustrations, making them easier to understand and memorize different concepts. Although there is no choice on whether to read the docs or listen to them, sometimes there are additional links to recorded talks, so I believe someone might find them helpful.

Code Samples

Another great way to learn is a mix of theory and practical examples. The React docs do precisely that with their interactive examples. They include use cases that closely resemble real-life scenarios, helping you better understand how to apply the concepts in practical situations. You can browse the whole code used to develop the example. You can see with your own eyes how performance issues affect the web app and how React solves this issue. You can check how the 'useEffect' hook fires twice in the development environment and detect the calls in the console. You can even tweak the code to see the difference yourself.

What’s also great is that the examples highlight the changes, making it easier to spot the differences and understand the code snippet.

That fulfills all the principles of good code samples described in Docs for Developers:

• Explained - A paragraph always discusses the code example.

• Concise and Clear - It’s simple enough not to overwhelm users.

• Usable and Extensible - It’s easy to understand the results. You can run the code and even modify it. It’s also easy to copy and use the example in your project.

• Trustworthy - You can see the results, and the code seems well-maintained.

Deep Dives

I love the deep dives, where things that are not so obvious are explained. If there is some less common use case, you can easily skip the section, but if you are curious, you can unwrap and read it. There are also pieces of information that help you understand what’s under the hood. It’s an excellent solution for beginner users who can skip complex parts and for advanced users interested in more elaborate explanations.

Guidance

The docs provide a lot of guidance that helps you better understand certain concepts.. Documentation pages start with the “You will learn” section, which includes bullet points summarizing the key information. When reading the documentation, you will probably omit those sections, but it proves invaluable when you want to find some information quickly.

“Pitfall” sections also warn you about mistakes like performance issues. There are also “Note” sections that explain some additional things, such as the old ways of writing React code.

Organization and Navigation

In Docs for Developers, there are three approaches to organizing the documentation. The documentation sites can be navigated in three primary ways: sequences, hierarchies, and webs.

In React documentation, you can notice the sequence in the learn section. It’s for developers who want to learn React and read it like a book - page by page. At the end of each page, the buttons will navigate to the previous and next pages.

React documentation is also divided into hierarchical structures. The learn and reference pages are divided into sections that group documentation together to make browsing easier. In learn, there are pages such as “Describing the UI” which are parent pages to pages such as “Your First Component”. This makes it easier to navigate documentation if you are looking for a specific topic.

Learn is divided into sections such as “Describing the UI” which focuses on rendering, “Adding Interactivity” which explains how to react to user actions in the app, and “Managing state” which dives deep into more complex examples of shaping the state. Finally, an “Escape Hatches” section focuses on more complex topics such as effects or refs.

The reference part of React documentation is more like a web structure. It’s possible to read it as a sequence, and there are also parent pages that, for example, group all the hooks. The reference seems more like a web structure because most pages are interlinked, connecting “Learn” and “Reference” documentation.

Search

Search is also handy in this documentation. Documentation is pretty long, so it’s essential to have a tool to search for something you need. Search results are also divided into two sections - Learn and React APIs, which allow you to find exactly the code you need or a more descriptive piece of documentation with examples.

What could be better?

Overall, I feel like it’s perfect documentation. I’ve used many resources to learn new technologies, but React documentation was the most pleasant to follow. Being able to put myself in the position of the receiver instead of the creator of documentation gave me some ideas.

Documentation should be repetitive because it’s really easy to miss something important if it’s just stated once. On the other hand, making documentation too repetitive makes it more boring when reading page by page. I love using React documentation as a reference, but it was tough to skip parts I already knew while reading it all. I was worried that I would miss out on something important.

This documentation strikes a balance between being a reference and a course that you can read from front to back to learn React. I was a bit disappointed that after going through all the crucial topics, the guidance stopped, and there was no more “learn” documentation. You must go to reference documentation and find topics such as Fragments, useMemo, or React 18 concurrent features on your own.

It’s easier to understand why documentation is written this way if you look at the form that gathers feedback about documentation. One question explains the purpose of the documentation and how complex it is to achieve all of them.

“What task did you want to accomplish on react.dev?”

• Find an API reference,

• Troubleshoot a problem,

• Learn React,

• Debug an error.

What to use in your project?

One source of inspiration could be gathering feedback. The React documentation asks for simple thumbs-up feedback, while a more detailed form allows users to share additional insights. I think it’s even more critical if your documentation is not user-facing but internal. There is less chance that someone notices something is wrong if your documentation is rarely used. You might not see that something is obsolete or hard to use. You need to think about the maintenance process and how to gather feedback.

Structure and navigation are other things to use. React documentation is straightforward to navigate. There is a navigation bar with sections and a detailed search. The documentation pages start with “You will learn” sections. When creating documentation, it’s important to think about the audience that will use it and develop some improvements so it’s easier to discover the essential parts of the documentation.

Summary

When I compare the APIs and resources created ten years ago, I notice a trend of simplifying and improving quality. This is all done to improve the developer experience and ship more software. I hope that React documentation will serve as an example for other tools. Making the documentation more accessible to developers makes the tool more popular and often used in commercial projects, so it helps improve the product itself.

Being on the receiving end of documentation taught me the importance of discoverability, simple examples, and additional information for more curious people. I also got a few ideas for gathering feedback, and I’ll try to use them in my projects. After reading the documentation from top to bottom, those are the most important takeaways.

---

You Might Like Too

Here are a few articles I came across recently that I found insightful:

• Why Writing Architecture Docs Is Painful (And How to Fix It) by Thomas Johnson

• 7 proven mental models for engineering managers by Michał Poczwardowski and Anton Zaides

• The Silent Art of Comment Mastery by Akos Komuves

1. Levie, W.H., Lentz, R. Effects of text illustrations: A review of research. ECTJ 30, 195–232 (1982). https://doi.org/10.1007/BF02765184