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
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.
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 important fact is missing, do not block forever. Make the narrowest reasonable assumption and label it clearly.
2) Inventory facts before prose
Collect the facts that often go stale:
- package names
- install commands
- runtime and framework versions
- supported browsers or environments
- environment variables
- URLs, endpoints, ports, callback paths
- permissions, auth requirements, keys, tokens
- build, test, and deploy commands
- breaking changes or constraints
If you cannot verify a fact, avoid inventing it. Use a clearly marked placeholder or assumption.
3) Build the page skeleton first
Before writing full paragraphs, create a skeleton with the exact sections the page needs.
Preferred order:
- context
- prerequisites
- steps or body
- verification / expected result
- next steps / related pages
4) Write for the first successful run
Every task page should help the reader get one successful outcome as early as possible.
That means:
- front-load the shortest working path
- minimize branching
- postpone advanced options
- prefer one package manager and one framework unless the project truly supports several first-class entry points
- show what success looks like
5) Make examples runnable
Examples should be copy-pasteable or easy to adapt.
- Use real filenames and realistic directories.
- Label code fences.
- Keep examples minimal but complete.
- Add comments only where they remove ambiguity.
- If a command is destructive or billable, warn first.
- Show expected output or visible result after important steps.
6) Tighten the prose
After the draft exists:
- shorten intros
- split long paragraphs
- convert vague headings into task-based headings
- remove duplicated explanation
- move theory out of procedural pages
- move detail out of landing pages
7) Run the review checklist
Use assets/review-checklist.md before delivering.
Reference files
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.
How to respond in common task modes
When asked to write a page from scratch
Deliver:
- the appropriate page type
- a polished Markdown draft
- clearly marked assumptions if any important facts are unknown
When asked to improve existing docs
Do this in order:
- identify the current page type
- remove mixed modes
- tighten structure
- rewrite for clarity
- preserve technical meaning
- call out factual gaps or staleness risks
When asked to review docs
Return:
- the page type
- the top issues in priority order
- exact rewrite suggestions
- missing sections
- any staleness or trust issues
When asked to design a docs site
Return:
- audience segments
- entry points
- page types needed
- sitemap
- priority order for authoring
- gaps and risks
Files in this skill
assets/documentation-brief-template.md — collect facts before writing
assets/docs-ia-template.md — structure a docs site or section
assets/docs-home-template.md — landing page skeleton
assets/readme-template.md — README skeleton
assets/quickstart-template.md — happy-path setup guide
assets/tutorial-template.md — learning-by-doing guide
assets/how-to-template.md — task-focused guide
assets/reference-template.md — API/reference skeleton
assets/explanation-template.md — mental-model page
assets/troubleshooting-template.md — symptom-first troubleshooting
assets/migration-guide-template.md — upgrade/migration page
assets/review-checklist.md — final quality gate
references/house-style.md — voice, length targets, page-type patterns
references/web-project-rules.md — web-project checklists, code rules, anti-patterns
references/research-notes.md — why these rules exist
Final instruction
The best documentation pages feel easy because the writer made a hundred careful choices for the reader:
- what belongs on this page
- what does not
- what comes first
- what to cut
- what to verify
- what to explain
- what to defer
Make those choices deliberately.
1---
2name: writing-web-documentation
3description: 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.
4license: MIT
5metadata:
6 source: https://skillmd.com/skills/onmax/writing-web-documentation
7---
8
9# Writing web documentation
10
11Use 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.
12
13Good documentation is not a dump of product facts. It is a guided path through the product for a reader with a specific goal.
14
15## What this skill optimizes for
16
171. **Fast first success**
18 A new reader should reach a working result quickly.
19
202. **Clear routing by intent**
21 A beginner learning the product and an expert checking an option should not have to fight the same page.
22
233. **Low ambiguity**
24 Commands, file names, versions, prerequisites, expected outcomes, and failure states should be explicit.
25
264. **Scannability**
27 Busy developers skim before they read. Headings, intros, lists, tables, and code blocks should make the page navigable at a glance.
28
295. **Maintenance**
30 Docs should age gracefully, be easy to update with code changes, and make stale information obvious.
31
32## Non-goals
33
34Do **not** optimize for:
35
36- hype
37- marketing language
38- exhaustive background on every page
39- showing every supported variation in the first document
40- clever prose
41- giant code dumps with little explanation
42
43## First decide: what kind of page is this?
44
45Never draft before choosing the page type. Keep page types distinct.
46
47### README or docs landing page
48
49Use for orientation and routing.
50
51- Answer: What is this? Who is it for? Where do I start?
52- Keep it short.
53- Push deep detail into child pages.
54
55### Quickstart
56
57Use for the fastest happy path to a working result.
58
59- One path.
60- One main environment.
61- Minimal branching.
62- Clear prerequisites and a visible success state.
63
64### Tutorial
65
66Use to teach by doing.
67
68- The reader builds something meaningful.
69- Include checkpoints and a recap.
70- Explain enough for learning, not enough for encyclopedia coverage.
71
72### How-to guide
73
74Use to solve one concrete problem.
75
76- Assumes the reader already knows the basics.
77- Focus on outcome, not background theory.
78
79### Reference
80
81Use to answer precise factual questions.
82
83- Syntax, options, defaults, parameters, return values, events, errors, limits, compatibility.
84- Dry, complete, easy to scan.
85
86### Explanation / concept page
87
88Use to build mental models.
89
90- Why the system works this way.
91- Architecture, trade-offs, invariants, decision rules.
92- Link outward to task docs and reference docs.
93
94### Troubleshooting page
95
96Use to diagnose problems by symptom.
97
98- Symptom -> likely cause -> fix -> verify -> prevention.
99
100### Migration guide
101
102Use when versions, APIs, or architecture change.
103
104- Make breakage explicit.
105- Show before/after.
106- Give a safe order of operations.
107- Include rollback guidance when relevant.
108
109## The default workflow
110
111Follow this workflow unless the user asks for something narrower.
112
113### 1) Identify the reader and job
114
115Infer or state:
116
117- reader type: beginner, experienced user, maintainer, integrator, API consumer, platform engineer
118- task: learn, set up, integrate, customize, debug, migrate, deploy, contribute
119- environment: framework, runtime, package manager, OS, browser, hosting target
120- success state: what the reader should be able to do after finishing
121
122If any important fact is missing, do **not** block forever. Make the narrowest reasonable assumption and label it clearly.
123
124### 2) Inventory facts before prose
125
126Collect the facts that often go stale:
127
128- package names
129- install commands
130- runtime and framework versions
131- supported browsers or environments
132- environment variables
133- URLs, endpoints, ports, callback paths
134- permissions, auth requirements, keys, tokens
135- build, test, and deploy commands
136- breaking changes or constraints
137
138If you cannot verify a fact, avoid inventing it. Use a clearly marked placeholder or assumption.
139
140### 3) Build the page skeleton first
141
142Before writing full paragraphs, create a skeleton with the exact sections the page needs.
143
144Preferred order:
145
146- context
147- prerequisites
148- steps or body
149- verification / expected result
150- next steps / related pages
151
152### 4) Write for the first successful run
153
154Every task page should help the reader get one successful outcome as early as possible.
155
156That means:
157
158- front-load the shortest working path
159- minimize branching
160- postpone advanced options
161- prefer one package manager and one framework unless the project truly supports several first-class entry points
162- show what success looks like
163
164### 5) Make examples runnable
165
166Examples should be copy-pasteable or easy to adapt.
167
168- Use real filenames and realistic directories.
169- Label code fences.
170- Keep examples minimal but complete.
171- Add comments only where they remove ambiguity.
172- If a command is destructive or billable, warn first.
173- Show expected output or visible result after important steps.
174
175### 6) Tighten the prose
176
177After the draft exists:
178
179- shorten intros
180- split long paragraphs
181- convert vague headings into task-based headings
182- remove duplicated explanation
183- move theory out of procedural pages
184- move detail out of landing pages
185
186### 7) Run the review checklist
187
188Use `assets/review-checklist.md` before delivering.
189
190## Reference files
191
192Load these on demand based on current task:
193
194| Reference | Purpose |
195| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
196| **[references/house-style.md](references/house-style.md)** | Voice, sentence style, headings, length targets, page-type patterns |
197| **[references/web-project-rules.md](references/web-project-rules.md)** | Web-project checklists, code example rules, anti-patterns, accessibility, docs-as-code |
198| **[references/research-notes.md](references/research-notes.md)** | Research synthesis from strong documentation sites and style guides |
199
200**DO NOT load all files at once.** Load only what's relevant to your current task.
201
202## How to respond in common task modes
203
204### When asked to write a page from scratch
205
206Deliver:
207
2081. the appropriate page type
2092. a polished Markdown draft
2103. clearly marked assumptions if any important facts are unknown
211
212### When asked to improve existing docs
213
214Do this in order:
215
2161. identify the current page type
2172. remove mixed modes
2183. tighten structure
2194. rewrite for clarity
2205. preserve technical meaning
2216. call out factual gaps or staleness risks
222
223### When asked to review docs
224
225Return:
226
227- the page type
228- the top issues in priority order
229- exact rewrite suggestions
230- missing sections
231- any staleness or trust issues
232
233### When asked to design a docs site
234
235Return:
236
237- audience segments
238- entry points
239- page types needed
240- sitemap
241- priority order for authoring
242- gaps and risks
243
244## Files in this skill
245
246- `assets/documentation-brief-template.md` — collect facts before writing
247- `assets/docs-ia-template.md` — structure a docs site or section
248- `assets/docs-home-template.md` — landing page skeleton
249- `assets/readme-template.md` — README skeleton
250- `assets/quickstart-template.md` — happy-path setup guide
251- `assets/tutorial-template.md` — learning-by-doing guide
252- `assets/how-to-template.md` — task-focused guide
253- `assets/reference-template.md` — API/reference skeleton
254- `assets/explanation-template.md` — mental-model page
255- `assets/troubleshooting-template.md` — symptom-first troubleshooting
256- `assets/migration-guide-template.md` — upgrade/migration page
257- `assets/review-checklist.md` — final quality gate
258- `references/house-style.md` — voice, length targets, page-type patterns
259- `references/web-project-rules.md` — web-project checklists, code rules, anti-patterns
260- `references/research-notes.md` — why these rules exist
261
262## Final instruction
263
264The best documentation pages feel easy because the writer made a hundred careful choices for the reader:
265
266- what belongs on this page
267- what does not
268- what comes first
269- what to cut
270- what to verify
271- what to explain
272- what to defer
273
274Make those choices deliberately.