Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing.
Use this skill when you need to create, review, or improve technical documentation following the Diátaxis framework. Examples include:
Organize documentation into four distinct types — tutorials, how-to guides, reference material, and explanations — each serving different user needs and contexts.
Always ask clarifying questions about the user's context, audience, and goals before creating documentation.
Use the following decision checklist based on user signals:
| User signal | Documentation type |
|---|---|
| "I'm new to X and want to learn it" / "walk me through" | Tutorial |
| "How do I…?" / "I need to accomplish X" | How-to guide |
| "What are the parameters/options/syntax for X?" | Reference |
| "Why does X work this way?" / "Help me understand X" | Explanation |
Quick decision tree:
Example intro:
"In this tutorial, you will build a simple REST API using Express. By the end, you will have a running server that responds to GET requests. No prior Express experience is needed."
Example intro:
"This guide shows how to add JWT authentication to an existing Express app. It assumes you have a working Express server and basic familiarity with middleware."
Example entry:
timeout(integer, default:5000) Maximum time in milliseconds to wait for a response before the request fails. Example:{ timeout: 3000 }
Example intro:
"Authentication and authorisation are often confused. This page explains the distinction, why both matter, and how common patterns (sessions, tokens, OAuth) approach each concern differently."
| Type | Validation check |
|---|---|
| Tutorial | Can a beginner complete it end-to-end without external help? |
| How-to guide | Does it solve the stated problem for an experienced user? |
| Reference | Can the user find a specific fact in under 30 seconds? |
| Explanation | Does the user understand the why, not just the what? |