documentation

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 3f067ed6a979 · 20 Oct 2026Report an issue or request a re-scan

• Publishermcollina GitHub userOwner of the repository this skill is read from
• Source foldermcollina/skills/skills/documentationThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict3f067ed6a979A new audit runs when the source changes
• Repository statusNot archivedLast push 2 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: 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…

---
name: documentation
description: "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."
metadata:
  tags: documentation, technical-writing, tutorials, guides, reference, diataxis
---

## 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*? |

Excerpt, first 5,402 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/mcollina/skills
git -C skills checkout 3f067ed6a979

Works in

1. 2026-10-20
   ✓SAFE B 89 / 100

   first audit · source 3f067ed6a979

Questions about documentation

• github.com/mcollina/skills/tree/main/skills/documentation — the audited source at commit 3f067ed6a979 and every finding aboveObserved · 20 Oct 2026

Spotted something wrong? Report a correction · Methodology