Designing Effective Documentation: Lessons Learned Building the Redux Docs

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.

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.

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.

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.

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.

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.

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!