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.
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.
Fast first success A new reader should reach a working result quickly.
Clear routing by intent A beginner learning the product and an expert checking an option should not have to fight the same page.
Low ambiguity Commands, file names, versions, prerequisites, expected outcomes, and failure states should be explicit.
Scannability Busy developers skim before they read. Headings, intros, lists, tables, and code blocks should make the page navigable at a glance.
Maintenance Docs should age gracefully, be easy to update with code changes, and make stale information obvious.
Do not optimize for:
Never draft before choosing the page type. Keep page types distinct.
Use for orientation and routing.
Use for the fastest happy path to a working result.
Use to teach by doing.
Use to solve one concrete problem.
Use to answer precise factual questions.
Use to build mental models.
Use to diagnose problems by symptom.
Use when versions, APIs, or architecture change.
Follow this workflow unless the user asks for something narrower.
Infer or state:
If any important fact is missing, do not block forever. Make the narrowest reasonable assumption and label it clearly.
Collect the facts that often go stale:
If you cannot verify a fact, avoid inventing it. Use a clearly marked placeholder or assumption.
Before writing full paragraphs, create a skeleton with the exact sections the page needs.
Preferred order:
Every task page should help the reader get one successful outcome as early as possible.
That means:
Examples should be copy-pasteable or easy to adapt.
After the draft exists:
Use assets/review-checklist.md before delivering.
Load these on demand based on current task:
| Reference | Purpose |
|---|---|
| references/house-style.md | Voice, sentence style, headings, length targets, page-type patterns |
| references/web-project-rules.md | Web-project checklists, code example rules, anti-patterns, accessibility, docs-as-code |
| references/research-notes.md | Research synthesis from strong documentation sites and style guides |
DO NOT load all files at once. Load only what's relevant to your current task.
Deliver:
Do this in order:
Return:
Return:
assets/documentation-brief-template.md — collect facts before writingassets/docs-ia-template.md — structure a docs site or sectionassets/docs-home-template.md — landing page skeletonassets/readme-template.md — README skeletonassets/quickstart-template.md — happy-path setup guideassets/tutorial-template.md — learning-by-doing guideassets/how-to-template.md — task-focused guideassets/reference-template.md — API/reference skeletonassets/explanation-template.md — mental-model pageassets/troubleshooting-template.md — symptom-first troubleshootingassets/migration-guide-template.md — upgrade/migration pageassets/review-checklist.md — final quality gatereferences/house-style.md — voice, length targets, page-type patternsreferences/web-project-rules.md — web-project checklists, code rules, anti-patternsreferences/research-notes.md — why these rules existThe best documentation pages feel easy because the writer made a hundred careful choices for the reader:
Make those choices deliberately.