Writing Web Documentation

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:

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.

[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

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

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

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:

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

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]

[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](#)

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

[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](#)

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

[command]

Explain what this does and what files it creates.

2. Install dependencies

[command]

3. Configure environment variables

Create [filename]:

[command or file creation step]

[example env vars]

Explain which values are examples and which are required.

4. Start the development environment

[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

[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

# 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)

project/
  src/
  ...

Contributing

Link to contribution guidance.

License

State the license.

[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

[code]

### Example with common options

[code]

## Related pages

- [How-to guide](#)
- [Concept page](#)
- [Troubleshooting](#)

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.

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

[diagnostic command]

Fix

[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

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.

[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](#)

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

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

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