writing-web-documentation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: writing-web-documentation
description: Write, rewrite, review, and organize developer-facing documentation for web software projects. Use when creating or improving README files, docs homepages, quickstarts, tutorials, how-to guides, API/reference pages, conceptual explanations, migration guides, or troubleshooting content for frontend, backend, full-stack, SDK, API, or framework-based web products. This skill applies strong information architecture, task-first page structure, clear voice, runnable examples, version and prerequisite hygiene, accessibility rules, and docs-as-code maintenance habits. Do not use it for marketing copy, legal text, or non-technical customer-support articles.
license: MIT
---

# Writing web documentation

Use this skill when the user wants excellent technical documentation for a web project, not merely "some text around the code." The job is to produce documentation that is easy to enter, easy to scan, easy to trust, and easy to maintain.

Good documentation is not a dump of product facts. It is a guided path through the product for a reader with a specific goal.

## What this skill optimizes for

1. **Fast first success**
   A new reader should reach a working result quickly.

2. **Clear routing by intent**
   A beginner learning the product and an expert checking an option should not have to fight the same page.

3. **Low ambiguity**
   Commands, file names, versions, prerequisites, expected outcomes, and failure states should be explicit.

4. **Scannability**
   Busy developers skim before they read. Headings, intros, lists, tables, and code blocks should make the page navigable at a glance.

5. **Maintenance**
   Docs should age gracefully, be easy to update with code changes, and make stale information obvious.

## Non-goals

Do **not** optimize for:

- hype
- marketing language
- exhaustive background on every page
- showing every supported variation in the first document
- clever prose
- giant code dumps with little explanation

## First decide: what kind of page is this?

Never draft before choosing the page type. Keep page types distinct.

### README or docs landing page

Use for orientation and routing.

- Answer: What is this? Who is it for? Where do I start?
- Keep it short.
- Push deep detail into child pages.

### Quickstart

Use for the fastest happy path to a working result.

- One path.
- One main environment.
- Minimal branching.
- Clear prerequisites and a visible success state.

### Tutorial

Use to teach by doing.

- The reader builds something meaningful.
- Include checkpoints and a recap.
- Explain enough for learning, not enough for encyclopedia coverage.

### How-to guide

Use to solve one concrete problem.

- Assumes the reader already knows the basics.
- Focus on outcome, not background theory.

### Reference

Use to answer precise factual questions.

- Syntax, options, defaults, parameters, return values, events, errors, limits, compatibility.
- Dry, complete, easy to scan.

### Explanation / concept page

Use to build mental models.

- Why the system works this way.
- Architecture, trade-offs, invariants, decision rules.
- Link outward to task docs and reference docs.

### Troubleshooting page

Use to diagnose problems by symptom.

- Symptom -> likely cause -> fix -> verify -> prevention.

### Migration guide

Use when versions, APIs, or architecture change.

- Make breakage explicit.
- Show before/after.
- Give a safe order of operations.
- Include rollback guidance when relevant.

## The default workflow

Follow this workflow unless the user asks for something narrower.

### 1) Identify the reader and job

Infer or state:

- reader type: beginner, experienced user, maintainer, integrator, API consumer, platform engineer
- task: learn, set up, integrate, customize, debug, migrate, deploy, contribute
- environment: framework, runtime, package manager, OS, browser, hosting target
- success state: what the reader should be able to do after finishing

If any impor