documentation

When to use

Use this skill when you need to create, review, or improve technical documentation following the Diátaxis framework. Examples include:

• Creating user guides

• API documentation

• Tutorial content

• Restructuring existing documentation to better serve different user needs and contexts

Instructions

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.

Step 1 — Identify the documentation type

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:

• Is the user learning by doing for the first time? → Tutorial

• Do they need to solve a specific problem they already understand? → How-to guide

• Do they need technical facts to look up? → Reference

• Do they want conceptual background? → Explanation

Step 2 — Apply type-specific patterns

#### Tutorials (learning-oriented)

• Title pattern: Start with a verb — "Build your first X", "Create a Y from scratch"

• Structure: Goal → Prerequisites → Numbered steps → Immediate verifiable result at each step → Final outcome

• Minimise explanation; maximise doing

• Every step must produce a visible, testable result

• Validation: A beginner must be able to complete the tutorial without external help

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

#### How-to guides (problem-oriented)

• Title pattern: Frame as a task — "How to configure X", "How to deploy Y to Z"

• Structure: Goal statement → Assumptions/prerequisites → Numbered steps → Expected result

• Assume baseline knowledge; skip conceptual explanations

• Allow for variation; note alternatives where they exist

• Validation: An experienced user can complete the task without confusion or backtracking

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

#### Reference (information-oriented)

• Title pattern: Name the thing — "Configuration options", "API endpoints", "CLI flags"

• Structure: Consistent repeatable format per entry (name → type → default → description → example)

• State facts; avoid instruction beyond minimal usage examples

• Keep current; version-stamp if needed

• Validation: A user can look up a specific fact in under 30 seconds without reading surrounding content

Example entry:

**timeout** (integer, default: 5000)

Maximum time in milliseconds to wait for a response before the request fails.

Example: { timeout: 3000 }

#### Explanations (understanding-oriented)

• Title pattern: Frame as a concept — "How X works", "Understanding Y", "Why Z is designed this way"

• Structure: Context → Core concept → Alternatives/trade-offs → Higher-level perspective

• Avoid step-by-step instruction or technical specification

• Validation: After reading, the user can explain the concept in their own words and understands the rationale behind design decisions

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

Step 3 — Maintain separation and integration

• Keep each document a single type — don't mix tutorial steps with reference tables or conceptual digressions

• Cross-link between types: a tutorial can link to the relevant reference page; a how-to guide can link to an explanation for background

• Use consistent headings and terminology across all types so users can navigate the full documentation system

Step 4 — Validate before delivering

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?