We fixed our documentation with the Diátaxis framework

Diátaxis recently made the front page of HN. I mentioned in a comment that we applied the framework to Sequin a couple weeks ago and were very happy with it. Some folks asked me to expand on my comment, so I'm doing so here:

The engineer's documentation fallacy

Engineers often approach documentation backwards. We certainly did.

The engineer's impulse is to explain everything upfront. We felt that the most efficient thing for us to do was communicate how our product works and why we built it. Surely, with that mental model, the reader would "get" it.

So, our first and most important docs page used to be "How Sequin works".

Logically, this is the fastest way to transfer a mental model. But this pg_dump/pg_restore approach on the human brain didn't seem to work.

We would do Zoom sessions with folks where we watched them read our docs. After they read through some, we'd have them explain to us what Sequin was. Starting with "How Sequin works" felt like a chore. It was like we were asking them to study for a test. And they never really seemed to "get it" until they got their hands on the product anyway.

Then we found Diátaxis and realized we were explaining. And explanation is the wrong place to start.

What is Diátaxis?

Ironically, Diátaxis doesn't do a good job of describing itself on its website! I wished the authors used plainer language. Diátaxis hides what it is instead of just spitting it out.

Here's what you need to know:

1. Diátaxis is a framework for documentation.
2. In Diátaxis, every document belongs to one of four categories.
3. Diátaxis has guidelines for how each category of document should be written.
4. Diátaxis recognizes that readers will naturally progress through the different categories of documents. Your docs should support a certain flow. (More below.)

The four categories of docs pages:

• Tutorials
• How-to guides
• Reference
• Explanation

How I'd break them down:

Tutorials are lessons designed to help beginners learn by doing. A quickstart is a tutorial. In a tutorial, the reader is on rails: you have a specific destination that you are taking them to, and are giving them the exact steps to get there.

A reader should be able to follow a tutorial from start to finish without thinking much or doing any decision-making. This means you might provide them a sandbox environment or sample data.

In how-to guides, you are helping the reader reach a destination of their choosing. How-tos have steps. But you're not working on a precise example with the reader, together. Instead, you're telling them how they can do something with your product and their problem. And providing guidance along the way around trade-offs, navigating challenges, etc.

Reference is pure technical information that users consult while working. It's like a map or dictionary – factual, precise, and structured to help find specific details quickly. Think API documentation or command references. You don't read it cover to cover; you look things up when needed.

Explanation provides background and illumination. You read it when you want to truly understand something. It answers "why" questions. It's like reading about the science of cooking versus following a recipe.

Per #4 above, Diátaxis recognizes that users naturally progress through documentation in stages.

They start with hands-on learning (tutorials), move to solving specific problems (how-tos), dive into details as needed (reference), and finally explore deeper understanding (explanation). This mirrors how we learn any complex skill – from basic competence to mastery.

Here's the example that helped it click for me:

Imagine you're shopping for a piece of cooking equipment, like a pressure cooker.

The first thing you're going to look at is the "quickstart" (tutorial) – how does this thing work generally? You just want to see it go from A to B.

Then, you're going to wonder how to use it to cook a particular dish you like. That's a how-to.

If you're really curious about anything you've seen so far, then you'll flip to the reference to read more about it. For example, you might check the exact minutes needed for different types of beans.

And finally, when you're really invested in pressure cooking and want to understand the science behind it – why pressure affects cooking times, how the safety mechanisms work, etc. – that's when you'll read the explanatory content.

Note this flow applies both when evaluating your product as well as using it. Those two stages are often entangled.

By starting with quickstarts, you are taking readers on a fast-track journey over a few minutes to see your product in action, hands-on. You remove all decision-making to make it as easy as possible for them. If your product is interesting to them, you just won a little more of their attention.

How-tos require a little more thought. In a how-to, the reader is thinking about how your product will help them solve a problem that they are familiar with. How-tos bridge the gap between basic tutorials and detailed reference material. When writing a how-to guide, you're showing a competent user how to solve a real-world problem.

Investment from the reader ramps up from there, from reference to explanation.

How we transformed our docs

As some background, our product, Sequin, is a change data capture tool for Postgres. We capture all inserts/updates/deletes that happen in Postgres, and stream them in real-time to streams and queues like Kafka and SQS.

Here's how we upgraded our docs:

Start with the quickstart (tutorial)

The first thing we focused on was making really great quickstarts (tutorials). This was a tight loop between creating the quickstart and improving the product at the same time.

For example, originally our quickstart started with connecting a Postgres database. Then, we'd have you create a table to use in the rest of the quickstart.

But we've all been through a hundred Postgres connection flows. I think ours is pretty great, but it's not core to what makes Sequin special.

So instead, we decided to package a logical playground database in our Docker compose. Our quickstart cuts right to creating a sink (e.g. webhook endpoint) and seeing changes flow from the source table to the destination.

We removed a TON of explanation and lessons from the quickstart. We no longer tell you about filtering or grouping or other basic features. We just want you to see changes from Postgres flow from the insert statement to the webhook endpoint or SQS queue. That's the only win we're trying to get you to.

Our quickstart takes like ~3 minutes from start to finish, which I think is about right.

How-to guides reveal product gaps

How-to guides were next, and they taught us something unexpected: they're a great tool for product development.

When you write how-to guides, you're forced to think through real user scenarios. "How do I order records correctly when streaming Postgres to Kafka?" "How do I build an event-driven workflow on top of Postgres change data capture?" You can't hide behind abstraction – you have to show exactly how to solve concrete problems.

Writing these guides surfaced dozens of product improvements. If we felt awkward explaining a workflow, that was a signal our product needed work. If a guide felt too complex, we'd revisit the feature design.

Whenever we felt the urge to explain a concept, we'd create a "phantom link" to a non-existent reference page. This created a natural map of what reference documentation we actually needed.

Reference docs: just the facts

By the time we reached reference docs, we had a clear blueprint from all our phantom links. Writing reference docs became mechanical: document the facts without teaching or guiding.

More importantly, we learned that isolating reference material makes everything else better. Quickstarts and how-to guides became clearer because we weren't trying to wedge in every technical detail. Reference pages became more useful because they had a single, clear purpose.

Leverage Claude

We loaded up a Claude project with all the pages in the Diátaxis website repo. Claude ended up being super helpful throughout our transformation!

When we finished a doc, we'd paste into a new Claude conversation in the project. Claude did a surprisingly good job of providing targeted feedback.

As engineers, we had to constantly fight the temptation to explain everything at every turn. Claude kept us honest. It caught us when we strayed, or when we were mixing e.g. reference material into a how-to.

After a few loops with Claude, we fully "got" it.

Before & after

Here's what our docs sidebar looked like before and after the changes:

Before

- Get started
  - Introduction
  - Quickstart
    - Setup
    - Consume with webhooks
    - Consume with API 
    - Capture changes
  - How Sequin works
  - Compare
  - CLI
  - Self-hosting/Docker setup

- Stream
  - Consumer Group API
    - Overview
    - Receive
    - Ack
    - Nack

- Destinations
  - Webhooks

- Capture changes
  - Change capture pipelines

- How-to guides
  - Audit logging

- Database setup
  - GCP
  - RDS
  - ...

- Tutorials
  - Timescale
  - Cloudflare
  - ...

After

- Get Started
  - Introduction
  - Quickstarts
    * Webhooks
    * SQS
    * Kafka
    * Redis
    * GCP PubSub
    * Sequin Stream
  - Compare
  - Running Sequin
  - Connect Postgres

- Sink Setup Guides
  - Stream Postgres to Webhook
  - Stream Postgres to SQS
  - Stream Postgres to Kafka
  - Stream Postgres to Redis
  - Stream Postgres to Sequin Stream
  - Stream Postgres to GCP PubSub

- How-to Guides
  - Setup Change Retention
  - Trigger Automated Workflows
  - Create Audit Logs
  - Replicate Tables
  - Maintain Caches
  - Deploy to Production

- Reference
  - Configuration
  - Databases
  - Messages
  - Filters
  - Backfills
  - Change Retention
  - Sequin YAML
  - CLI Overview

- Sink Reference
  - Overview
  - Webhooks
  - SQS
  - Kafka
  - Redis
  - GCP PubSub
  - Sequin Stream
  - Sequin Stream API

- Database Setup Guides
  - Setup RDS
  - Setup Azure
  - ...etc

- Webhook Destinations
  - Cloudflare
  - Inngest
  - ...etc

- Management API
  - Introduction
  - Authentication
  - Errors

Granted, we also changed our product and focus at the same time. But you can see a big change. Before:

• We had quickstarts, but they were too long and inter-dependent (they all relied on "Install & setup"). Then we led right into explanation and reference.
• The "Consume" and "Capture changes" sections were both reference.
• "Database setup" was how-to.
• "Common patterns" was very out of place and didn't fit into any category.
• The "Guides" were in a purgatory between tutorials and how-tos.

Now on our sidebar:

• Built out "Quickstarts" for every sink.
• "Running Sequin" and "Connect Postgres" are both how-tos.
• "Sink setup guides" are how-tos.
• Clear homes for all reference materials.
• "Database setup guides" are how-tos.
• "Webhook destinations" have been turned into how-tos.

We actually have very little in the way of explanation now. There's more we want to do here, but the highest ROI is on quickstarts, how-tos, and complete reference pages.

Key takeaways

1. Start with hands-on experience, not explanation. Your instinct as an engineer might be to explain everything upfront, but users need to see your product in action first.
2. Quickstarts should be ruthlessly focused. We cut our quickstart down to one core "aha moment" - seeing changes flow from Postgres to a destination. Everything else could wait.
3. How-to guides are product development tools. Writing them forces you to think through real user problems and workflows. If a guide feels awkward to write, it's probably highlighting a product issue.
4. Reference documentation works best in isolation. Separating pure technical facts from tutorials and guides makes all your documentation clearer and more purposeful.

Most importantly, Diátaxis helped us recognize that documentation isn't just about transferring information. You have to win the time and attention of users. Meet them where they are, and guide them through a natural learning progression.