Designing Effective Documentation: Lessons Learned Building the Redux Docs

This ad is not shown to multipass and full ticket holders
React Summit US
React Summit US 2025
November 18 - 21, 2025
New York, US & Online
The biggest React conference in the US
Learn More
In partnership with Focus Reactive
Upcoming event
React Summit US 2025
React Summit US 2025
November 18 - 21, 2025. New York, US & Online
Learn more
Bookmark
Rate this content

You've just finished building a brand-new blazing fast JS library and can't wait to publish it to NPM. But hold on a minute - what about the docs? Sure, anyone can slap together a README with some example code snippets, but have you actually thought about how to actually design the docs themselves?

Join Redux maintainer Mark Erikson as we look at ways to effectively structure and write documentation to help your users learn and understand how to use your tools, based on years of experience building the Redux docs.  We'll talk about patterns for organizing categories of documentation, tips for making the docs easier to read and understand, useful tools for working with docs content, and more!

This talk has been presented at React Advanced 2024, check out the latest edition of this React Conference.

FAQ

Mark Erickson is a senior front-end engineer at Replay, a Redux maintainer, and a writer known for his contributions to Redux documentation and his Simpsons avatar.

The talk focuses on designing effective documentation for software libraries, particularly within the JavaScript ecosystem, sharing organizational techniques and practical tips.

Documentation is essential for understanding what a tool does, how to use it, and providing API details, as users don't inherently know how to use a library.

Taxonomy in documentation refers to the classification and organization of information, making it easier to navigate and understand.

The Divio or Diataxis model is a framework for organizing documentation into four categories: tutorials, how-to guides, explanations, and references.

The four categories are tutorials, how-to guides, explanations, and references, each serving different purposes like learning, solving specific problems, understanding concepts, and providing API details.

Tutorials are learning-oriented documents that teach users how to use a library by guiding them through building an application or project step-by-step.

Tutorials are for learning and step-by-step guidance, while how-to guides are goal-oriented, focusing on solving specific problems with assumed prior user knowledge.

Mark Erickson builds the final version of an example app, reverse-engineers it to teach concepts in the right order, and writes step-by-step explanations with practical examples.

Mark Erickson recommends using Markdown with static site builders like Docusaurus, Starlight, MKDocs, or Notaku for generating documentation sites.

Mark Erikson
Mark Erikson
22 min
28 Oct, 2024

Comments

Sign in or register to post your comment.
Video Summary and Transcription
Hi, I'm Mark Erickson, and today I'm very happy to talk to you about designing effective documentation, lessons I've learned writing the Redux docs. We'll discuss organizational techniques, practical tips, writing tutorials, and useful documentation tools. Redux offers learning-oriented tutorials and goal-oriented how-to guides. Other documentation categories include reference guides, explanations, readme files, FAQ pages, and release notes. Tips for organizing and writing documentation: consider the target reader, assume prerequisite knowledge, repeat information, cover topics in multiple areas. Writing tutorials for libraries in TypeScript presents challenges but can be tackled with TypeScript-first approach and keeping examples up-to-date. Engaging tutorials involve interactive exercises, diagrams, and formatting, and should be reviewed and improved based on feedback. Overall, documentation is valuable and worth the effort.

1. Introduction

Short description:

Hi, I'm Mark Erickson, and today I'm very happy to talk to you about designing effective documentation, lessons I've learned writing the Redux docs. A few things about today's talk. We're going to talk about the organizational techniques for writing docs, practical tips, thoughts on writing tutorials specifically, and useful documentation tools. The need for documentation arises from the need to understand what a tool does, how to use it, and provide details on API contents. Organizing information into taxonomies is challenging, but the Divio or Diataxis four categories model is a good starting point. The first category is tutorials.

Hi, I'm Mark Erickson, and today I'm very happy to talk to you about designing effective documentation, lessons I've learned writing the Redux docs. A few quick things about myself. I am a senior front-end engineer at Replay. I am an answerer of questions. I'll answer questions pretty much anywhere there's a text box on the Internet. I collect all kinds of useful and interesting links. I am a writer of extremely long blog posts and I am a Redux maintainer, but most people know me as that guy with the Simpsons avatar.

A few things about today's talk. This is going to be primarily focused on writing docs for software libraries. A lot of the tips are probably useful in writing documentation for other things as well, but the main assumption here is that we're writing docs for the JavaScript ecosystem. We're going to talk about some organizational techniques for writing docs, practical tips, thoughts on writing tutorials specifically, and finally look at a couple useful documentation tools.

So, why do we need documentation anyway? A number of different reasons. We need to be able to understand what a tool does and when to actually use it. People need to be able to know how do you use a tool when you don't have any prior knowledge about how it actually works. You may need to understand specific questions about how to use a tool and we want to be able to provide details on what an API contains. Unfortunately, the reality is that users don't automatically know how to use our library and so we need to be able to provide that information for them.

There's a great word that describes organizing information and that is taxonomy. It's the science of classifying and categorizing things. Now, this is primarily used around things like species and physical anatomy but it also applies to documentation and information as well. And organizing information into taxonomies is hard. If you've ever had a bunch of files on your computer and you're confused about what folder do I put these in, you've understood the problem of trying to organize information.

There are a lot of different ways that you can try to organize documentation. A lot of different categories a lot of different patterns. There isn't a single best pattern and different projects are going to have different needs. Having said that, I am a big fan of the Divio or Diataxis four categories model which divides documentation into four primary categories. Tutorials how-to guides, explanations, and references. This was originally authored by someone named Danielle Procida originally published under a company called Divio and it was later reworked and given the name of Diataxis and published at its own site. And there are some differences between the two different sites. And it's not perfect, but this is a really good starting point for thinking about how to actually organize your documentation.

So the first category is tutorials.

2. Tutorials and How-to Guides

Short description:

And these tutorials are learning-oriented, aiming to teach users how to understand and use the library step by step. Redux has two primary tutorials: Redux Essentials, which focuses on practical usage and building features, and Redux Fundamentals, which explains concepts from scratch. Additionally, there are how-to guides that are goal-oriented and focused on solving specific problems. These guides assume readers have a decent amount of knowledge and understanding, allowing for focused explanations on solving specific problems, such as setting up Redux with Next.js.

And these are learning oriented. The goal is to teach the user how to understand and use the library step by step. Often by going through the process of building some kind of an actual application or project from start to finish. And the goal is to teach them how to use the tool. So by the time they're done, they ought to be able to start using your library successfully and they ought to be able to go through the other sections in the docs and actually understand what things are talking about.

In the case of Redux, we have two primary tutorials. The first is the Redux Essentials tutorial. And the goal of this one is to teach people how to use Redux Toolkit and React Redux to build a realistic application. The focus here is on how. And we talk about the patterns and we go through a lot of the core concepts, but we don't always talk about the why or how these abstractions actually work internally. And so this is a very practically focused tutorial. We spend a lot of time building features and showing how to use specific methods out of Redux Toolkit.

But different people learn in different ways. Some people want to dive in and just show me how to do this thing. Other people feel kind of stuck until they understand the why and how does this actually work from the bottom up. So we also have a Redux Fundamentals tutorial. And the goal of this one is to teach each of the concepts from scratch. No abstractions, no layers, no libraries. And work our way up from the bottom and show how each of these pieces actually works. So it's practical in that we're showing real working code but it's a little more theoretical in that we're trying to explain the thinking behind each of these concepts. In fact, a lot of common Redux patterns don't even get introduced until late in this tutorial after we've already explained the basics. And then finally it shows how Redux Toolkit simplifies a lot of the patterns.

Another category is how-to guides. And these are very goal-oriented. These are recipes or focused on solving specific problems. And really these are going to be things that only actual users of an application or a library are, with some actual experience, are going to be asking. The good news about these is that you can assume that the reader already has a decent amount of knowledge and understanding and that they already know the basics. And so you can focus the explanations on solving this one specific problem. So with Redux we have a lot of how-to guides. We have things like how do you set up Redux with Next.js, which has a lot of very complicated nuances.

3. Other Documentation Categories

Short description:

We have pages on migrating legacy code, writing custom middleware, and more. Reference guides focus on the API and usage examples. Explanations provide understanding and context, including topics like selector functions, Redux style guide, and the history of Redux. Other documentation categories include readme files, FAQ pages, and release notes.

We have a page on migrating legacy code to modern Redux. A page on writing custom middleware, and many more. These are very focused on here is a specific problem that you might run into if you're using Redux and here's what you need to know in order to work with that problem effectively.

The third category is reference guides. And these are information oriented. And these are probably going to be focused around the API of your library and what specific methods and classes and types are included. Now reference guides can include examples and they can include basic usage. Here's how to actually use this API correctly. That's different from the how-to guides, which were focused on how do you achieve a specific result. Each of the different Redux libraries has its own API reference section.

And the final category from this Divio Diataxis approach is explanations. And these are supposed to be understanding oriented. It's talking about the big picture, the background context, giving opinions. How do you actually think about this particular concept? So in the case of Redux we have pages like selector functions. What are they? Why do they exist? How do they work? The Redux style guide which talks about best practices and patterns for using Redux. Or even the history of Redux which talks about its creation and its evolution over time. Now there are a lot of categories of documentation that don't fall neatly into these four. For example, your project is going to have a readme file. And this is really the first introduction to a project. It's what people will see when they look at the GitHub repo or they look at a package on npm. And so it should probably have some information about what is this project? How do you get set up? A link to the actual documentation. Maybe a few other useful pieces as well. FAQ pages that have answers to very specific questions about using the library. This is a little bit like a usage guide or a how to. But also maybe a little more focused on literal questions. Release notes are very important.

4. Documentation Categories: FAQ and Release Notes

Short description:

FAQ pages provide specific answers to questions. Release notes are crucial for understanding the changes in each version of the library.

FAQ pages that have answers to very specific questions about using the library. This is a little bit like a usage guide or a how to. But also maybe a little more focused on literal questions. Release notes are very important. Every time you put out a new version of your library people want to know, how big is this change? Is there a risk of any of my code breaking? What has changed? Being able to see the issues in the PRs that actually got changed as well. These are all types of documentation and they don't necessarily fall into those four categories we talked about earlier. So taxonomies are hard.

5. Organizing Documentation and Tips

Short description:

Should specific information and examples go on API reference pages or a separate usage category? How to organize documentation categories and handle informational content. Tips for writing documentation: consider the target reader, assume prerequisite knowledge, repeat information, cover topics in multiple areas. Example from Redux: covering async logic and thunks in different tutorials. FAQ pages should be used sparingly, add FAQ content to other sections if possible.

Some of the questions that I've run into working on the Redux docs. If I have specific information about how to use the TypeScript types properly or some specific usage examples, should those go on the API reference pages for these methods? Or should they go under a completely separate usage category?

In the Redux docs we have a usage section and frankly we've got some pages on there that are probably more of a how-to and some of them that are more of an explanation section. Do they really both go under usage? What about things that are purely informational? Should we have a separate understanding category for those? And what kind of category is an FAQ page anyway? Again, there's no specific answers but these are the things you have to think about as you're trying to organize information in docs.

Some additional tips for writing documentation. One is to keep the target reader in mind. It really helps to know who is going to be reading these documentation pages. What's their experience level? What do they want to know out of this? As well as what are you going to assume as their background? Your docs can't explain everything and each documentation page is going to assume certain amounts of knowledge.

Whether it's things that they should know from other pages of the docs already or things that you have to assume that they know before they even looked at your docs at all. So it's very helpful to make the prerequisite knowledge very clear up front. In the case of the Redux tutorials, I have to assume that a lot of our readers are going to be people who are straight out of a boot camp. Maybe they've had a month of JavaScript, a month of React, a month of Redux. Go. So I have to assume that they're pretty fresh.

At the same time, we can't spend time in our documentation explaining how to use JavaScript and HTML in React. So we clearly call out that these are prerequisites. We assume that you know these things up front. We even provide some links to resources on where to learn these topics and that way we don't have to spend time and content explaining these things in our tutorials. It's also very helpful to repeat information multiple times in different sections of the documentation. It helps to call out things up front that says this page is going to cover these topics and then at the end have a recap that actually summarizes the things that you explained in this page.

Additionally, cover the same topic in multiple areas of the docs in different ways. Users might be reading through the tutorials and learn things that way. They might come with a specific question about a concept or a term. And so having the information covered in multiple ways increases the chance that they'll actually find the information they want to learn. In the case of Redux, we have multiple pages that talk about async logic and data fetching and thunks. We cover it in the Essentials tutorial where we talk about the createAsyncThunk method and we give just enough details on what a thunk is, but focus more on how to use this method properly. The Redux Fundamentals tutorial goes into more detail on the middleware and how it works and the concept of using middleware for side effects. And then we have a usage page called Writing Logic with Thunks which talks specifically about the name and the concept and patterns that you might see when using Thunks. So there's some overlap in information between these pages, but all of them are very relevant.

FAQ pages are a useful concept, but they can also be overused as well. When you actually add information and you answer questions in an FAQ page, it's worth trying to see how you can actually add that to other sections of the docs as well.

6. Writing Tutorials and TypeScript Documentation

Short description:

For libraries written in TypeScript, decide if docs will be TypeScript first or JS first. Revamping Redux Essentials tutorial to be TypeScript first. Use fake TypeScript types for better readability. Keep example blocks and code up-to-date. Use Remark TypeScript Tools for doc blocks and compilation. Challenges in writing tutorials: balancing realism and complexity, teaching concepts in the right order, assuming linear learning path. Redux Essentials tutorial: 8 sections, 53,000 words, starts with basic concepts, builds practical app step by step. Reverse engineering process for tutorial development.

That way people might be reading a tutorial and see it and learn a particular concept and then they might actually never have to go to the FAQ page in the first place because they sort of learned that naturally in the process of reading. On the other hand, it is still useful to have specific links to FAQs so that you can point people to that knowledge directly. For libraries that are written in TypeScript, you have to decide if your docs are going to be written TypeScript first or JS first. And this covers both the API references and the tutorials. I actually just got done revamping the Redux Essentials tutorial to be TypeScript first. I always had concerns about it being an extra layer of knowledge that beginners would have to deal with when trying to learn Redux, but ultimately we want our users using Redux, using TypeScript with Redux. And so I put in a lot of effort this year to revamp the tutorial, make the example app TypeScript all the way through, teach TypeScript in the actual tutorial content. And so we really do want people using TypeScript with Redux. Now sometimes in sections like the API references, if you try to show readers the real TypeScript types for your library, they might not be very helpful, especially if those types are complex or very derived. So sometimes you might need to kind of write fake TypeScript types that are simpler and easier for someone to read when they're looking at the reference. TypeScript does allow you to have good information in the JS doc section for a method. And that can actually be extracted and embedded directly in your documentation site. Similarly, it's also good to make sure that the example blocks are actually up-to-date with the current code that's in the repository. And you can actually compile those during the docs build step. And so for both the doc blocks and the compilation step, we use a package that was created by my co-maintainer, Lenz Weber, called Remark TypeScript Tools, which we use the TypeScript compiler to both compile snippets as well as give the TypeScript JavaScript toggle tabs in the references as well.

A few quick things about writing tutorials. As I said earlier, the Redux Essentials tutorial is the primary tutorial that we want to learn Redux with. We take them from zero to building a practical application. And they do it by building a pseudo-social media app, like a little Facebook, a little bit Twitter. It's over 53,000 words at this point. I've been told that I should write a book, and I basically did. And there were a lot of challenges with doing this. When you're writing a tutorial, you want the example app to be realistic and practical enough that it feels like the reader is actually doing something, but it can't be so complex that they are getting distracted and bogged down by irrelevant concepts and code. It's also very hard to figure out how do I teach the concepts in the right order, but it all should still feel like a natural progression as we're just building out this app. We do sort of have to make the assumption that there's going to be a linear learning path, that the reader is going to go through the whole thing start to finish. And then something that I struggled with is for TypeScript. Do we do the whole thing in JavaScript and then show the TypeScript layer at the end, or do we do TypeScript the whole way through? So what we've got is eight sections, 53,000 words, that starts with basic concepts, shows a standalone counter-app example where we can point out all the different pieces and how they connect together. And then parts three through eight build up a practical app, step by step, where we go from adding the Redux store, writing the first slice, dispatching the first action, all the way up through selectors and data fetching and finishing with RTK Query for actually building real apps. In my process, and this won't be true for everybody, but what I did was I came up with the example app, I built the very final version of it from scratch myself, and then I sort of reverse engineered things. If I was to build the app and make the changes over time, what concepts would I want to teach and what order would I want to teach them in? So I very carefully made a Git commit history that showed step by step, here's all the pieces that I would build up over time, and then how I would iterate to add more layers.

7. Tips for Writing Engaging Tutorials

Short description:

Tips for tutorials: engage readers with interactive exercises, diagrams, and formatting. Use in-page sandboxes to show running application and code. Link to related documentation pages or add expandable detailed explanation sections. Get feedback and review. Common pattern: write content in Markdown and use static site builder. Documentation is valuable and worth the effort.

And then I went back through that code content and I wrote the actual tutorial explanations that said, first we're going to add a Redux store, then we're going to add a slice, then we're going to add this form. And I built up everything from there.

A few quick tips for tutorials, try to find ways to keep the reader engaged. If you can add interactive exercises or challenges, that's definitely worth doing. Diagrams are good, formatting to call out specific text or concepts is very helpful. If you can add in-page sandboxes that both show the running application and the code that drives it at that point in time, that's very helpful. Link to other documentation pages, maybe you've introduced a concept, you give a brief explanation, but you link to a usage guide or a how-to page that gives more details. Or add expandable detailed explanation sections. That way the reader doesn't get bogged down, but the information is there if they want to look at it.

And definitely have things get reviewed. When I got done with my recent revamp of the Redux Essentials tutorial, a couple folks were kind enough to go through the whole thing start to finish and they gave me some very valuable feedback about explanations that were unclear or things that could be improved and that made the final result a lot better. Finally, while there's lots of ways to write docs today, the most common pattern is writing the content as Markdown and then using a static site builder to generate the docs. So, this is a lot of the things that I've learned over the years from writing documentation for the Redux docs. I'm not the world's greatest expert, but I've picked up a lot of these things over time, and hopefully these resources will be useful to you as well. So, documentation is valuable. It's worth putting the time into. Your library's users will thank you, and hopefully this information helps a lot. Take care! Thank you for watching!

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
Why You Should Use Redux in 2024
React Summit 2024React Summit 2024
33 min
Why You Should Use Redux in 2024
Top Content
Mark Erickson explains the history, creation, evolution, and benefits of Redux. Redux was designed to make state updates and action history maintenance easy, incorporating functional programming principles. Redux Toolkit was created to simplify Redux usage. Redux is still a valid choice for its consistent pattern and separation of state from UI. The decision to use Redux depends on the specific use case and the need for centralized state management.
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.