Content types

Most docs problems are mode confusion — a page trying to be a tutorial AND a reference AND an explanation all at once, serving none of those needs well. Diátaxis (by Daniele Procida) is the cleanest framework for fixing this. Four modes, defined by what the reader is doing AT THE MOMENT THEY READ:

The Diátaxis compass

The framework positions each mode on two axes:

                 ACQUIRE                  APPLY
                (learning)               (doing)
        ┌─────────────────────┬────────────────────────┐
PRACTICAL│     TUTORIAL       │     HOW-TO GUIDE       │
(steps) │  teaches by doing  │  helps finish a task   │
        ├─────────────────────┼────────────────────────┤
THEORY  │    EXPLANATION     │     REFERENCE          │
(ideas) │ builds understanding│  describes the thing  │
        └─────────────────────┴────────────────────────┘

Acquire vs apply: is the reader learning or doing? Practical vs theory: is the page about steps or about ideas?

Most docs pages should fit cleanly in ONE quadrant. Pages straddling two quadrants usually signal "this needs to be split".

Diátaxis by voice

Same content, four different voices:

Tutorial voice

# Your first Acme integration

In this tutorial, we'll create an Acme account, install the SDK,
and send your first test payment. By the end, you'll have a working
integration you can iterate on.

## Before you start

You'll need Node.js 18+ and a terminal. If you've used any npm
package before, this will feel familiar.

## 1. Create an Acme account

Head to acme.com/signup. You can use your personal email — we'll
stay in sandbox mode the whole tutorial.

...

Key markers: first-person plural (we'll), encouraging tone (you'll have...), familiar pacing (Before you start), hand-holding (If you've used...).

How-to voice

# Add a custom domain

Add a CNAME record pointing to `cname.nookdocs.site`, add the domain
in Settings → Custom domains, wait for verification.

## DNS

```dns
docs.acme.com.  IN  CNAME  cname.nookdocs.site.

Verify

Open Settings → Custom domains → Add. The check polls every 5 seconds for 60 seconds. Green when the CNAME propagates.

Key markers: imperative (`Add`, `Open`), terse, no hand-holding, assumes reader knows the stack.

### Reference voice

```markdown
# Rate limit headers

Every API response includes three rate-limit headers.

| Header | Type | Semantics |
|---|---|---|
| `X-RateLimit-Limit` | integer | Requests allowed per window. |
| `X-RateLimit-Remaining` | integer | Requests remaining in current window. |
| `X-RateLimit-Reset` | integer (unix) | Timestamp when the window resets. |

Windows are fixed 60-second intervals aligned to UTC.

Key markers: no narrative, structured data (table), exhaustive, lookup-friendly.

Explanation voice

# Why we rate-limit per API key, not per IP

We debated this for weeks. Per-IP limits are industry standard —
they're what AWS, GitHub, and Stripe use. We went with per-API-key
because most of our customers deploy behind corporate NAT: one
shared IP for hundreds of developers. Per-IP rate-limiting would
have given a 100-engineer startup the same budget as a hobbyist.

Per-API-key has its own tradeoffs — an abusive key can exhaust its
budget and cascade-fail other services calling the same endpoint.
We accept that because...

Key markers: first-person plural (we debated), narrative arc, explicit tradeoffs, historical context.

Common mistakes

Mistake 1: tutorial-reference hybrid

The page starts as a tutorial ("let's create your first integration") then halfway through turns into exhaustive reference ("full list of all config options: …"). The reader was in learning mode and got dumped into look-up mode. Neither mode got served.

Fix: split. Tutorial keeps one happy path with just the fields you need; reference doc covers every field comprehensively.

Mistake 2: how-to with theory

The page claims to be a how-to ("Add a custom domain") but half the prose explains why DNS propagation takes up to 48 hours and how Let's Encrypt works under the hood. The reader wanted to finish the task; you gave them a lecture.

Fix: one-sentence framing, then steps. If the theory matters, link to an explanation page. Don't inline.

Mistake 3: reference with marketing

The API reference page starts with "Our powerful rate-limiting system protects your infrastructure while scaling effortlessly..." The reader scanning for the X-RateLimit-Remaining header has to scroll past 200 words of marketing.

Fix: reference is dispassionate. Marketing lives on the landing page.

Mistake 4: explanation as FAQ

The page labeled "Rate limits explained" is actually 15 Q&A pairs. Not wrong, but the FAQ format fragments what could be a narrative with clear cause-and-effect. FAQs are great for common objections; explanation is better for "why we designed X the way we did".

Fix: pick one or the other. If it's genuinely 15 disconnected questions, FAQ is right. If there's a through-line, write the narrative.

How to split a mixed page

If you have a single page trying to be all four modes (common in "Complete Guide to X" posts), split by quadrant:

NookDocs's own application

Looking at this site's current pages through the Diátaxis lens:

The pattern lands cleanly: /guides/ hosts explanations, /cli/ + /deploy/ host how-tos, /configuration/ + /components/ host references, tutorials live at top-level entry points like /quickstart.

When to ignore Diátaxis

Diátaxis is a framework, not a law. Cases where a hybrid page works:

• Very short features. A 300-word page on a tiny feature can legitimately cover all four modes if each mode is ~75 words. Splitting would be overkill.

• Changelog entries. An <Update> entry is mode-agnostic by design — it announces what changed without pretending to be a tutorial.

• Landing pages. Index / overview pages intentionally mix modes because they're signposts, not destinations.

For anything 500+ words, apply the framework.

Related

• Diátaxis homepage — the full framework, with cross-domain examples

• Writing for LLMs — LLM-specific authoring patterns that apply across all four modes

• Style and tone — voice and register per mode

• GEO — AI search optimization — why smaller, focused pages rank better in AI answers