Designing Effective Documentation: Lessons Learned Building the Redux Docs

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.

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.

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.

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

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