assets/docs-home-template.md
# [Product name] documentation
> One sentence: what the product is and who it helps.
## Start here
Choose the path that matches what you want to do:
- **Get up and running fast**: [Quickstart](#)
- **Learn the core ideas**: [Core concepts](#)
- **Solve a specific task**: [How-to guides](#)
- **Look up precise behavior**: [Reference](#)
- **Fix a problem**: [Troubleshooting](#)
- **Upgrade safely**: [Migration guide](#)
## What [Product name] does
Briefly describe the product, without hype.
## Who this documentation is for
- Primary audience:
- Secondary audience:
- What they usually want to achieve:
## Recommended first step
Explain the fastest sensible starting point.
## Popular tasks
- [Task 1](#)
- [Task 2](#)
- [Task 3](#)
## Reference sections
- [API reference](#)
- [CLI reference](#)
- [Configuration reference](#)
- [Component / SDK reference](#)
## Support and contribution
- [Report a problem](#)
- [Contribute to the docs](#)
- [Repository](#)
assets/docs-ia-template.md
# Documentation information architecture template
Use this when planning a docs site or docs section.
## Audience segments
- New evaluator
- First-time implementer
- Daily user
- Advanced integrator
- Maintainer / contributor
- Operator / deployer
## Entry points
- README or docs home
- Quickstart
- Tutorials
- How-to guides
- Concepts / architecture
- Reference
- Troubleshooting
- Migration / release notes
- Contributing
## Recommended top-level structure
- Start here
- What this product is
- Quickstart
- Installation / setup
- Learn
- Tutorials
- Core concepts
- Solve tasks
- How-to guides
- Reference
- API / CLI / config / components
- Troubleshooting
- Migrate
- Contribute
## Page inventory
| Page | Page type | Audience | Goal | Priority |
| --------------- | --------------- | ------------------- | ------------------------------- | -------- |
| Docs home | Landing | All | Route readers to the right path | P0 |
| Quickstart | Quickstart | New users | First successful run | P0 |
| Core concepts | Explanation | New + intermediate | Mental model | P1 |
| Common task 1 | How-to | Existing users | Complete a real task | P1 |
| Reference | Reference | Existing + advanced | Precise lookup | P1 |
| Troubleshooting | Troubleshooting | Blocked users | Diagnose issues | P1 |
| Migration guide | Migration | Existing users | Upgrade safely | P2 |
## Routing rules
- New readers should never need the reference first.
- Experts should be able to jump directly to reference.
- Tutorials teach.
- How-to guides solve.
- Reference specifies.
- Explanations orient.
- Troubleshooting unblocks.
## Authoring order
1. Docs home
2. Quickstart
3. Reference stubs
4. Troubleshooting
5. Concept pages
6. High-value how-to guides
7. Deep tutorials
8. Migration / contributor docs
assets/documentation-brief-template.md
# Documentation brief
Use this before writing any page. Fill what you know; mark the rest as `Unknown` or `Assumption`.
## Project and audience
- Product / project name:
- One-sentence description:
- Primary audience:
- Secondary audience:
- Reader skill level:
- Reader's main job to be done:
- What should they be able to do after reading?
## Product facts
- Repository / package name:
- Main framework / language:
- Runtime versions:
- Package manager:
- Supported browsers / environments:
- Hosting / deployment target:
- Authentication model:
- Important limits or constraints:
## Writing target
- Page type:
- Why this page needs to exist:
- What question should it answer?
- What should be left to other pages?
## Setup facts
- Install command:
- Environment variables:
- Required accounts, keys, or services:
- Local development command:
- Test command:
- Build command:
- Deploy command:
## Example facts
- Smallest meaningful example:
- Expected output / visible success state:
- Common failure states:
- Dangerous / destructive steps to warn about:
## Freshness and maintenance
- Version or release this page targets:
- Known upcoming changes:
- Who owns this doc:
- What must be updated when the code changes?
## Assumptions / TODOs
- Assumption 1:
- Assumption 2:
- TODO 1:
- TODO 2:
assets/explanation-template.md
# Understanding [concept]
## Why this exists
Describe the problem the feature or architecture solves.
## The mental model
Explain the core idea in plain language.
## Key terms
- **[Term]**: definition
- **[Term]**: definition
## How the parts fit together
Describe the main components and their relationships.
## Important trade-offs
- Benefit:
- Cost:
- When to choose this approach:
- When not to choose it:
## Decision guidance
Use this section to help the reader decide between options.
## Common misconceptions
- Misconception:
- Reality:
## Related tasks and reference
- [Quickstart](#)
- [How-to guide](#)
- [Reference](#)
assets/how-to-template.md
# How to [solve one concrete problem]
## Goal
State the exact outcome.
## Before you begin
Assume the reader already knows the basics, but list any extra requirements.
- [Requirement 1]
- [Requirement 2]
## 1. [Action]
```bash
[command]
```
Explain only what the reader needs to know to succeed.
## 2. [Action]
```[language]
[code or config]
```
## 3. Verify the result
Describe how to confirm success.
## Variations
List only closely related variants.
## Related tasks
- [Related how-to](#)
- [Reference](#)
- [Troubleshooting](#)
assets/migration-guide-template.md
# Migrate from [old version] to [new version]
## Who should read this
State who is affected and who is not.
## What changed
Summarize the important behavioral or API changes.
## Breaking changes
- [Breaking change 1]
- [Breaking change 2]
- [Breaking change 3]
## Before you begin
- back up:
- note current version:
- read linked release notes:
- gather required credentials / environment details:
## Upgrade order
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Before / after examples
### Before
```[language]
[old code]
```
### After
```[language]
[new code]
```
## Verify the migration
Describe smoke tests or checks.
## Rollback / escape hatch
Explain how to recover if the migration fails.
## Related pages
- [Release notes](#)
- [Reference](#)
- [Troubleshooting](#)
assets/quickstart-template.md
# Quickstart: [Do the first useful thing]
## Outcome
By the end of this guide, you will have [working result].
**Time to complete**: [for example 10 minutes]
**Audience**: [for example new users]
**Assumptions**: [for example macOS/Linux, Node 22+, pnpm]
## Prerequisites
- [Account / API key / service]
- [Runtime version]
- [Package manager]
- [Any local tools]
## 1. Create or open the project
```bash
[command]
```
Explain what this does and what files it creates.
## 2. Install dependencies
```bash
[command]
```
## 3. Configure environment variables
Create `[filename]`:
```bash
[command or file creation step]
```
```env
[example env vars]
```
Explain which values are examples and which are required.
## 4. Start the development environment
```bash
[command]
```
## 5. Verify that it works
Describe the visible success state:
- URL to open
- CLI output to expect
- file to inspect
- API response to confirm
## What just happened
Brief explanation only if it helps the reader keep going.
## Next steps
- [Deeper tutorial](#)
- [Concept page](#)
- [Reference](#)
- [Troubleshooting](#)
assets/readme-template.md
# [Project name]
One sentence: what this project does and why someone would use it.
## Why this exists
Explain the practical problem the project solves.
## Who it is for
- Primary users:
- Typical use case:
- When this is a bad fit:
## Quickstart
```bash
# install
[install command]
# run
[start command]
```
Then open [local URL] or verify with [test command / expected result].
## What you can do next
- [Quickstart](#)
- [Documentation](#)
- [Examples](#)
- [API reference](#)
## Requirements
- Runtime:
- Package manager:
- Framework / platform:
- Browser or deployment assumptions:
## Common workflows
### [Workflow 1]
Short description and link.
### [Workflow 2]
Short description and link.
## Project structure (optional)
```text
project/
src/
...
```
## Contributing
Link to contribution guidance.
## License
State the license.
assets/reference-template.md
# [Feature / API / command / component] reference
## Summary
One or two sentences describing what this element does.
## Syntax
```[language]
[syntax or signature]
```
## Parameters / props / options
| Name | Type | Required | Default | Description |
| --------- | -------- | -------- | ------- | ------------------------- |
| `example` | `string` | Yes | — | Explain what it controls. |
## Returns / output
Describe return values, emitted events, generated files, or side effects.
## Behavior notes
- Ordering rules:
- Validation rules:
- Performance or caching behavior:
- Auth requirements:
- Security constraints:
## Errors
| Error / status | Meaning | How to fix |
| --------------- | ------------- | ---------- |
| `EXAMPLE_ERROR` | What happened | What to do |
## Compatibility / requirements
- Runtime:
- Browser support:
- Framework version:
- Permissions or scopes:
## Examples
### Minimal example
```[language]
[code]
```
### Example with common options
```[language]
[code]
```
## Related pages
- [How-to guide](#)
- [Concept page](#)
- [Troubleshooting](#)
assets/review-checklist.md
# Documentation review checklist
Use this before publishing.
## Reader fit
- [ ] The audience is clear.
- [ ] The page has one primary job.
- [ ] The page type is correct (landing, quickstart, tutorial, how-to, reference, explanation, troubleshooting, migration).
- [ ] Mixed page modes have been removed.
## Structure
- [ ] The most important information appears early.
- [ ] Headings are descriptive and scannable.
- [ ] Long paragraphs have been split.
- [ ] Prerequisites appear before actions.
- [ ] The next step is obvious.
## Technical accuracy
- [ ] Commands, file names, URLs, and config keys are plausible and consistent.
- [ ] Versions or environment assumptions are stated.
- [ ] Required environment variables are documented.
- [ ] Examples reflect the real product behavior.
- [ ] Destructive, billable, or security-sensitive steps are clearly warned.
## Example quality
- [ ] Code blocks are labeled with a language.
- [ ] Examples are minimal but runnable.
- [ ] Expected output or success state is shown where useful.
- [ ] Placeholders are clearly marked.
- [ ] Omissions are explained honestly.
## Writing quality
- [ ] Active voice is used by default.
- [ ] Present tense is used for general behavior.
- [ ] Second person is used for the reader.
- [ ] Jargon is defined or removed.
- [ ] Filler words ("just", "simply", "obviously") are gone.
- [ ] The prose is concise.
## Accessibility and inclusivity
- [ ] Link text is descriptive.
- [ ] Important images have alt text or a text equivalent.
- [ ] Screenshots are not used where text/code would work better.
- [ ] The wording is translation-friendly.
## Freshness and maintenance
- [ ] The page states version / release context if needed.
- [ ] Known stale assumptions have been removed or called out.
- [ ] Related pages are linked.
- [ ] The page can be maintained with future code changes.
## Trust
- [ ] Limitations are admitted.
- [ ] Failure modes are covered where relevant.
- [ ] No marketing fluff appears in task docs.
- [ ] The doc would still help a reader who skims it.
assets/troubleshooting-template.md
# Troubleshooting [product / feature]
Use symptom-first headings so blocked readers can scan quickly.
## [Exact error message or symptom]
### Likely cause
Explain the most common reason first.
### How to verify
```bash
[diagnostic command]
```
### Fix
```bash
[fix command]
```
```[language]
[config change or code]
```
### Confirm the fix
Describe the expected result.
### Prevention
Optional. Include only if useful.
---
## [Second error message or symptom]
Repeat the same structure.
---
## When to escalate
Explain what information to collect before asking for help:
- logs
- versions
- reproduction steps
- config excerpts
assets/tutorial-template.md
# Tutorial: [Build something meaningful]
## What you will build
Describe the final result in one short paragraph.
## What you will learn
- [Concept / skill 1]
- [Concept / skill 2]
- [Concept / skill 3]
## Prerequisites
- [Prior knowledge]
- [Tools]
- [Accounts / keys]
- [Starter repo if any]
## Before you start
Set expectations:
- how long it takes
- what environment the tutorial assumes
- whether the code is production-ready or educational
## 1. [First milestone]
Explain the goal of the step first.
```bash
[command]
```
```[language]
[code]
```
### Checkpoint
Tell the reader what success looks like now.
## 2. [Second milestone]
Repeat the pattern:
- goal
- action
- explanation
- checkpoint
## 3. [Third milestone]
Repeat as needed.
## Recap
Summarize what the reader built and what they learned.
## Next steps
- [How-to guide](#)
- [Reference](#)
- [Concept page](#)
references/house-style.md
# House style
## Voice
- Use **second person** for the reader.
- Use **active voice** unless passive genuinely improves clarity.
- Use **present tense** for general behavior.
- Sound calm, competent, and direct.
- Be friendly without being chatty.
## Sentence style
- Prefer short, concrete sentences.
- One idea per sentence when possible.
- One main idea per paragraph.
- Avoid filler words such as "simply," "just," "obviously," and "easy."
- Replace vague nouns like "this," "it," and "thing" when they hide the actor or object.
## Headings
- Use **sentence case**.
- Make headings descriptive and task-based.
- Avoid cute headings.
- A reader should understand the page structure by scanning only the headings.
Good:
- `Set up local development`
- `Configure environment variables`
- `Handle webhook retries`
Bad:
- `Before you begin your journey`
- `A few notes`
- `More details`
## Links
- Use descriptive link text.
- Do not use bare "click here" or "read more."
- Link to the specific destination the reader needs next.
## Lists and callouts
- Use numbered steps for ordered actions.
- Use bullets for unordered facts.
- Use warnings only for real hazards.
- Use notes sparingly.
## Length guidance by page type
These are house targets, not hard laws.
### README / docs landing
- Target: 300–900 words.
- Goal: orient and route.
- Deep explanations belong elsewhere.
### Quickstart
- Target: 5–15 steps, usually 500–1,500 words.
- Must include a visible success state.
### Tutorial
- Target: 800–2,500 words.
- Longer is acceptable only if checkpoints keep the reader oriented.
### How-to guide
- Target: as short as the task allows.
- Often 400–1,200 words.
### Reference
- Length is dictated by completeness.
- Optimize for lookup, not for narrative flow.
### Explanation
- Long enough to form a mental model.
- Usually shorter than a tutorial, denser than a quickstart.
### Troubleshooting
- Keep each problem entry short.
- Let readers scan by symptom.
## Page patterns
Use the matching template in `assets/`.
### README or docs landing page pattern
Required elements:
1. Product name and one-sentence value proposition
2. What it does
3. Who it is for
4. Fastest starting point
5. Links to key paths:
- quickstart
- concepts
- how-to guides
- reference
- troubleshooting
- contribution or support
6. Minimal install or local run snippet if appropriate
Avoid:
- long architecture essays
- huge changelogs
- every configuration option
- duplicate content from deeper pages
### Quickstart pattern
Required elements:
1. Outcome
2. Time to complete (optional but recommended)
3. Prerequisites
4. One happy path
5. Expected result
6. Next steps
Rules:
- one package manager if possible
- one deployment target if possible
- explain why a step matters when the reason is not obvious
- prefer a project the reader can run locally
### Tutorial pattern
Required elements:
1. What you will build
2. What you will learn
3. Prerequisites
4. Step-by-step build path
5. Checkpoints after important milestones
6. Recap
7. Next steps
Rules:
- teach progressively
- do not mix every alternative approach into the main flow
- explain cause and effect around each major step
### How-to guide pattern
Required elements:
1. Goal
2. Before you begin
3. Steps
4. Verify the result
5. Variations or related tasks
Rules:
- assume baseline familiarity
- no long conceptual intro
- no encyclopedic reference dump
### Reference pattern
Required elements, as relevant:
- summary
- syntax
- parameters / props / options
- defaults
- return values / events / side effects
- examples
- errors
- compatibility / requirements
- related pages
Rules:
- be complete
- be precise
- be easy to skim
- do not bury behavior in prose if a table or list is clearer
### Explanation pattern
Required elements:
1. The problem space
2. The mental model
3. Important terms
4. How the parts relate
5. Trade-offs and design choices
6. Decision guidance
7. Links to how-to and reference pages
Rules:
- explain _why_
- avoid turning explanation into step-by-step instructions
### Troubleshooting pattern
Required elements:
1. Symptom
2. Likely cause
3. How to verify the cause
4. Fix
5. How to confirm the fix
6. Prevention tips when helpful
Rules:
- index by the words users actually search for
- prefer concrete error messages in headings or subheadings
- keep each entry self-contained
### Migration guide pattern
Required elements:
1. Who should read this
2. What changed
3. Breaking changes
4. Upgrade order
5. Before / after examples
6. Verification
7. Rollback or escape hatch if available
Rules:
- highlight irreversible changes
- be brutally explicit about renamed APIs, removed defaults, and changed behavior
references/research-notes.md
# Research notes: what makes great web-development docs work
This file summarizes the patterns behind documentation that developers consistently find useful.
## What I studied
### 1. Diátaxis / Divio
Core lesson:
- Great docs separate four jobs: tutorials, how-to guides, reference, and explanation.
- Each kind of page needs a different writing mode and should stay distinct.
Why it matters:
- Readers arrive with different intents.
- A page that tries to teach, solve, specify, and philosophize at the same time usually does all four poorly.
Sources:
- https://diataxis.fr/
- https://docs.divio.com/documentation-system/introduction/
### 2. GitHub Docs and style guidance
Core lesson:
- Start from user needs.
- Choose the correct content type.
- Write for readability and scannability.
Why it matters:
- Busy readers scan first.
- Strong docs make the page legible through headings, code blocks, lists, and clear first sentences.
Sources:
- https://docs.github.com/en/contributing/writing-for-github-docs/best-practices-for-github-docs
- https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide
### 3. Google and Microsoft style guidance
Core lesson:
- Active voice, present tense, second person, clear hierarchy, descriptive links, and accessible images all improve clarity.
- Good code samples need context and should be easy to scan.
Why it matters:
- Technical writing works best when the reader always knows who does what, in what order, and what to expect.
Sources:
- https://developers.google.com/style
- https://developers.google.com/style/voice
- https://developers.google.com/style/tense
- https://developers.google.com/style/code-samples
- https://learn.microsoft.com/en-us/style-guide/grammar/person
- https://learn.microsoft.com/en-us/style-guide/developer-content/reference-documentation
### 4. MDN Web Docs
Patterns worth copying:
- Clear beginner entry points
- Structured learning path
- Practice and “test your skills” checkpoints
- Runnable examples through MDN Playground
- Code examples available in GitHub
- Visible page freshness and contribution links
Why developers like it:
- It gives beginners a safe path from zero to competence.
- It lets readers learn by editing real code.
- It makes the content feel alive and maintainable.
Sources:
- https://developer.mozilla.org/en-US/docs/Learn_web_development
- https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website
### 5. React docs
Patterns worth copying:
- A clear split between “Learn” and “Reference”
- The quick start explicitly states what the page teaches
- The reference is clearly marked as lookup material
Why developers like it:
- New users can learn without drowning in API detail.
- Experienced users can jump straight to the reference.
Sources:
- https://react.dev/learn
- https://react.dev/reference/react
### 6. Next.js docs
Patterns worth copying:
- Up-front system requirements
- Supported browser information
- Quick-start commands very near the top
- “Last updated” context on the page
- Edit-on-GitHub affordances
Why developers like it:
- Operational facts are not buried.
- The reader knows exactly what environment the docs assume.
- The content signals freshness and maintainability.
Sources:
- https://nextjs.org/docs/app/getting-started
- https://nextjs.org/docs/app/getting-started/installation
### 7. Stripe docs
Patterns worth copying:
- Quickstarts collected in one place
- Interactive, end-to-end code samples
- Multiple language and framework options where genuinely useful
- Test mode separated from live mode
Why developers like it:
- The docs are close to real integration work.
- It is easy to go from reading to trying.
- The product’s risky or irreversible contexts are made explicit.
Sources:
- https://docs.stripe.com/api
- https://docs.stripe.com/quickstarts
- https://docs.stripe.com/get-started
### 8. TypeScript docs
Patterns worth copying:
- Several “get started” paths based on reader background
- A handbook that can be read from top to bottom
- Clear distinction between introductory paths and deeper handbook material
Why developers like it:
- Readers do not all start from the same place.
- Background-based entry points reduce intimidation.
Sources:
- https://www.typescriptlang.org/docs/handbook/
- https://www.typescriptlang.org/docs/handbook/intro.html
### 9. Supabase docs
Patterns worth copying:
- Multiple framework-specific entry points
- Strong separation between getting started material and reference material
Why developers like it:
- Readers can begin from the stack they actually use.
- The docs match the way web developers think in frameworks and runtimes.
Sources:
- https://supabase.com/docs
- https://supabase.com/docs/reference/javascript/introduction
## Repeating patterns across the best docs
### 1. They route readers immediately
Great docs do not ask the reader to figure out the information architecture on their own.
They provide clear paths such as:
- start here
- quickstart
- learn
- reference
- troubleshoot
- migrate
### 2. They separate learning from lookup
This may be the single most important pattern.
- Tutorials and quickstarts are for doing and learning.
- Reference is for exact answers.
- Explanation builds mental models.
Mixing them creates slow, confusing pages.
### 3. They front-load the happy path
The best docs show the smallest useful success first.
They do not start with every option, every caveat, or every supported stack.
### 4. They show environment assumptions
Runtimes, versions, browsers, package managers, and prerequisites are stated early.
This prevents many avoidable failures.
### 5. They make examples usable
Developers like examples that can be copied, run, and modified.
The best docs use examples to solve real tasks, not to show off every feature.
### 6. They make scanning easy
Headings, short paragraphs, lists, code blocks, warnings, and tables let readers find what matters quickly.
### 7. They build trust
Visible version context, last-updated signals, contribution links, and honest limitations make docs more believable.
### 8. They support maintenance
Good docs are tied closely enough to the product that they can be updated with the code.
## What this skill intentionally turns into rules
From the research above, this skill bakes in the following defaults:
- choose the page type before writing
- write for one audience and one primary job
- separate landing, quickstart, tutorial, how-to, reference, explanation, troubleshooting, and migration pages
- lead with the fastest successful path
- state versions, assumptions, and prerequisites
- prefer active voice, present tense, second person, and descriptive headings
- make code examples minimal, realistic, and runnable
- review for scannability, accessibility, and freshness
- treat docs like something that must be maintained, not just published once
references/web-project-rules.md
# Web-project rules
## Web-project specifics
When documenting web software, check these items explicitly.
### Environment and versions
Always state or verify:
- runtime version (for example Node or Bun)
- framework version
- package manager used in examples
- supported browsers when relevant
- OS assumptions when commands differ
- whether examples target local development, staging, or production
### Local development
For setup docs, include:
- install command
- environment variable setup
- seed or sample data steps if required
- dev server command
- local URL
- how to verify the app actually works
### Frontend-specific topics
Cover these when relevant:
- routing model
- client/server boundaries
- rendering mode (SSR, SSG, CSR, streaming, edge)
- styling approach
- state management expectations
- accessibility requirements
- browser support and polyfills
- asset handling
### Backend / API topics
Cover these when relevant:
- authentication and authorization
- rate limits
- pagination
- idempotency / retries
- webhook signing / replay handling
- error format
- local testing or sandbox mode
- CORS or origin constraints
- caching behavior
### Deployment topics
When a page includes deployment:
- separate build-time and runtime configuration
- distinguish secrets from public environment variables
- state platform-specific caveats
- mention rollback, logs, and smoke tests when important
## Code example rules
1. **Solve a real task**
Examples should match something the audience actually wants to do.
2. **Start simple**
Show the smallest useful example first. Expand later.
3. **Be runnable**
Provide the imports, surrounding setup, and file paths the reader needs.
4. **Be easy to scan**
Prefer short blocks. Split large examples by step or file.
5. **Label placeholders clearly**
Use obvious placeholders like `YOUR_API_KEY` or `your-project-id`.
6. **Do not fake verification**
If a result is illustrative rather than guaranteed, say so.
7. **Show expected output when useful**
Especially for CLI steps, API responses, generated files, and visible UI changes.
8. **Avoid comment spam**
Comment the surprising lines, not every line.
9. **Never hide critical omissions**
If code is abbreviated, say exactly what is omitted.
10. **Prefer the project's dominant stack**
Do not multiply language or framework tabs unless the product truly supports them equally well.
## What developers tend to like in excellent docs
Use these as quality signals:
- the page tells them where to start
- examples work
- prerequisites are not buried
- the document type is obvious
- learning material and lookup material are separated
- the writer respects their time
- the page shows version or freshness context
- the docs admit limitations and failure modes
- the next step is obvious
## Common anti-patterns
Never ship these on purpose:
- a README that tries to be the entire documentation site
- a quickstart with many branches before the reader gets a first success
- a tutorial that reads like reference
- a reference page missing defaults, errors, or compatibility notes
- commands with hidden prerequisites
- screenshots used instead of copyable text for commands or config
- headings like `Overview`, `Notes`, `Details`, or `More`
- code blocks with no filename, no language, and no surrounding context
- unexplained acronyms or internal terminology
- stale version assumptions
- "works like magic" wording
- burying breaking changes below the fold
- writing as if the tool is the actor when the reader is the actor
## Accessibility and inclusivity rules
- Prefer descriptive link text.
- Provide alt text or a text equivalent for meaningful images.
- Do not rely on screenshots when text or code would be better.
- Keep sentences translation-friendly and jargon-light.
- Explain abbreviations on first use if they are not universal.
- Use examples that do not depend on hidden cultural context.
## Docs-as-code maintenance rules
Prefer documentation that can be maintained like code:
- keep docs near the code when practical
- update docs in the same change as the product behavior
- use review checklists
- keep examples tested or at least plausibly executable
- make "last updated" context visible when the platform supports it
- avoid orphan pages by linking related content
SKILL.md
---
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 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](references/house-style.md)** | Voice, sentence style, headings, length targets, page-type patterns |
| **[references/web-project-rules.md](references/web-project-rules.md)** | Web-project checklists, code example rules, anti-patterns, accessibility, docs-as-code |
| **[references/research-notes.md](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:
1. the appropriate page type
2. a polished Markdown draft
3. clearly marked assumptions if any important facts are unknown
### When asked to improve existing docs
Do this in order:
1. identify the current page type
2. remove mixed modes
3. tighten structure
4. rewrite for clarity
5. preserve technical meaning
6. 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.