Designing Effective Documentation: Lessons Learned Building the Redux Docs

Rate this content
Bookmark

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

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

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.

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.

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.

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.

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

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 Divio or Diataxis model is a framework for organizing documentation into four categories: tutorials, how-to guides, explanations, and references.

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

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.

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.