1 min lesson
Four doc types, four different jobs
Say what this means in practice: "Most weak docs fail because the writer blended two doc types into a soup that serves neither."
Step 1 of 3
Four doc types, four different jobsDiátaxis, applied to Cursor
Most weak docs fail because the writer blended two doc types into a soup that serves neither. A quickstart that tries to explain architecture loses the impatient reader. A reference page that tells a story can't be scanned. Know which one you're writing before the first sentence.
Learn more
Advanced table
Diátaxis names these four. The skill is refusing to mix them in one page
- Type
- Quickstart
- Reader's question
- "How do I get one win, fast?"
- What it must do
- Shortest path to a working result; zero detours.
- Cursor example
- Install the Agent SDKA programmatic interface for running Cursor agents from your own scripts, services or CI, locally or in the cloud. Press Enter for the full definition. and run your first agent in under five minutes.
- Type
- Tutorial
- Reader's question
- "Teach me by building something real."
- What it must do
- A guided narrative with a finished artifact at the end.
- Cursor example
- Build an MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. server that exposes your issue tracker to Agent modeCursor's full-capability mode: the AI can read the codebase, write and edit files, move them and run terminal commands. Contrast with Ask mode, which is read-only. Press Enter for the full definition..
- Type
- Conceptual
- Reader's question
- "How does this actually work?"
- What it must do
- Explain the model: agent loop, context, retrieval.
- Cursor example
- How codebase indexing and retrieval feed the model's context window.
- Type
- Reference
- Reader's question
- "What are the exact params and flags?"
- What it must do
- Complete, scannable, no narrative.
- Cursor example
- Every flag on the CLI agent and every field on the SDK config.
| Type | Reader's question | What it must do | Cursor example |
|---|---|---|---|
| Quickstart | "How do I get one win, fast?" | Shortest path to a working result; zero detours. | Install the Agent SDKA programmatic interface for running Cursor agents from your own scripts, services or CI, locally or in the cloud. Press Enter for the full definition. and run your first agent in under five minutes. |
| Tutorial | "Teach me by building something real." | A guided narrative with a finished artifact at the end. | Build an MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. server that exposes your issue tracker to Agent modeCursor's full-capability mode: the AI can read the codebase, write and edit files, move them and run terminal commands. Contrast with Ask mode, which is read-only. Press Enter for the full definition.. |
| Conceptual | "How does this actually work?" | Explain the model: agent loop, context, retrieval. | How codebase indexing and retrieval feed the model's context window. |
| Reference | "What are the exact params and flags?" | Complete, scannable, no narrative. | Every flag on the CLI agent and every field on the SDK config. |
Diátaxis names these four. The skill is refusing to mix them in one page.
Watch out
The most common docs failure is a "tutorial" that is secretly four things at once: it installs, explains theory, references every flag and tries to ship a real app. The reader who wanted a quickstart drowns. Pick one job. Link to the others.