#redux
SubscribeRedux is an open-source JavaScript library for managing and centralizing application state. It is most commonly used with libraries such as React or Angular for building user interfaces.
Designing Effective Documentation: Lessons Learned Building the Redux Docs
React Advanced 2024
22 min
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. 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. We need documentation to understand what a tool does and when to use it, how to use it without prior knowledge, and specific questions about using a tool. Organizing information into taxonomies is hard, but the Divio or Diataxis four categories model is a good starting point. The first category is tutorials. And these tutorials are learning oriented, teaching users how to understand and use the library step by step. Redux has two primary tutorials: Redux Essentials and Redux Fundamentals. The former focuses on practical usage, building features with Redux Toolkit. The latter teaches concepts from scratch, without abstractions or libraries. In addition, there are how-to guides, goal-oriented and focused on solving specific problems. We have focused pages on migrating legacy code to modern Redux, writing custom middleware, and more. The third category is reference guides, which provide information on the library's API, methods, and usage. Each Redux library has its own API reference section, covering core methods and those specific to Redux Toolkit and React Redux. The final category is explanations, offering understanding on concepts like selector functions, Redux style guide, and the history of Redux. Additionally, there are other documentation categories like readme files, FAQ pages, and release notes. Every time you put out a new version of your library, people want to know the size of the change, the risk of code breaking, and what has changed. The organization of documentation can be challenging, as certain information may not fit neatly into predefined categories. Additional considerations include whether to include specific usage examples in API reference pages or create a separate usage category. There's no one-size-fits-all answer, but it's important to keep the target reader in mind, assume prerequisite knowledge, and repeat information in different sections to cater to different learning preferences. FAQ pages can be overused but are still useful for specific links to FAQs. When adding information and answering questions, consider adding it to other sections of the docs as well. For TypeScript libraries, decide if the docs should be TypeScript first or JS first, including API references and tutorials. Revamping tutorials to be TypeScript first can help users learn Redux with TypeScript. Use fake TypeScript types in API references for readability, and ensure example blocks are up-to-date with the current code. Leverage packages like Remark TypeScript Tools for documentation and compilation. Writing tutorials can be challenging, but it's crucial to create a realistic yet practical example app. It's important to teach concepts in the right order and ensure a linear learning path. For TypeScript tutorials, decide whether to use JavaScript first or TypeScript throughout. Include interactive exercises, diagrams, and formatting to engage readers. In-page sandboxes and links to other documentation pages enhance the learning experience. Reviewing the tutorial and using tools like Docusaurus, Starlight, or MKDocs can improve the final result. Documentation is valuable and worth the effort for your library's users.
Why You Should Use Redux in 2024
React Summit 2024
33 min
Why You Should Use Redux in 2024
Top ContentMark 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.