App Documentation Generator

Browse a running web app, screenshot every screen, and produce documentation good enough to publish. Not a screenshot dump — a structured guide that teaches someone how to use the app.

Browser Tool Detection

Same as ux-audit — Chrome MCP, Playwright MCP, or playwright-cli.

URL Resolution

Same as ux-audit — prefer deployed/live URL over localhost.

Depth Levels

Depth

Screenshots

What it produces

Duration

quick

~10

Single-page quick-start guide. Key screens, happy path only.

10-15 min

standard

~30

Full user guide. All pages, primary workflows, reference tables.

30-60 min

thorough

~80+

Comprehensive guide. All states, mobile views, every CRUD flow, troubleshooting.

1-3 hours

exhaustive

~150+

Publishable documentation suite. Everything in thorough plus: getting started tutorial, feature-by-feature deep dives, admin guide, keyboard shortcut reference, FAQ, and HTML version.

3-6 hours

Default: standard

Workflow

1. Get App Details

Ask the user:

• App URL (required — or auto-detect from wrangler.jsonc / running dev server)

• App name (for the guide title)

• Auth — Chrome MCP uses their session; Playwright needs credentials

• Depth — quick, standard, thorough, or exhaustive

• Audience — who reads this? (end users, admins, new team members, clients)

2. Discover All Routes

Navigate the app and build a complete page inventory:

• Read the sidebar/navigation menu

• Click through all top-level items and sub-items

• Note sub-pages, tabs within pages, and nested navigation

• Check for settings, profile, admin areas, help pages

• Record the URL and purpose of each page

• Note which pages have interactive elements (forms, buttons, filters)

Create a task list to track documentation progress.

3. Document Each Page

For each page in the inventory:

#### a. Navigate and Prepare

• Navigate to the page

• Wait for data to load (no skeleton/spinner in screenshot)

• Resize browser to 1280x720 for consistent screenshots

• Make sure the page has realistic data — not "Test Client" or empty tables

#### b. Screenshot the Default State

• Take a clean screenshot showing the page populated with data

• Save to docs/screenshots/ with descriptive names

#### c. Write the Page Section

For each page, write:

## [Page Name]

[One sentence: what this page is for and when you'd use it]

![Page name](screenshots/NN-page-name.png)

### What You'll See

[Describe the key elements: sidebar shows X, main area shows Y, toolbar has Z]

### What You Can Do

[List the actions available, each as a brief description]

### How To: [Primary Action]

1. [Step with screenshot reference]

2. [Step]

3. [Step — screenshot the result]

> **Tip:** [Helpful shortcut or non-obvious feature]

#### d. Document Key Workflows

For interactive pages, document step-by-step with screenshots at each significant step:

### How To: Add a New Client

1. Click the **"Add Client"** button in the top right

   ![Add button location](screenshots/12-clients-add-button.png)

2. Fill in the required fields — Name and Email are required, everything else is optional

   ![New client form](screenshots/13-clients-new-form.png)

3. Click **"Save"** — you'll be taken to the new client's detail page

   ![Client saved confirmation](screenshots/14-clients-saved.png)

> **Tip:** You can also press **Cmd+N** from anywhere to create a new client.

#### e. Depth-Specific Extras

Extra

quick

standard

thorough

exhaustive

Empty states

Skip

Note

Screenshot + document

Screenshot + suggest improvements

Error states

Skip

Note

Trigger + screenshot

Every validation error documented

Dark mode

Skip

Skip

Screenshot key pages

Screenshot every page

Mobile (375px)

Skip

Skip

Screenshot key pages

Screenshot every page

All CRUD

Skip

Primary only

Every operation

Every operation + edge cases

Settings/config

Skip

List options

Document each

Document each with examples

Keyboard shortcuts

Skip

List if visible

Full reference table

Dedicated section

Search/filters

Skip

Mention

Document each filter

Document every combination

Permissions/roles

Skip

Skip

Note differences

Separate section per role

API/integrations

Skip

Skip

Mention if present

Document endpoints + examples

4. Write Supporting Sections

Beyond per-page documentation:

Getting Started (all depths):

## Getting Started

### Accessing [App Name]

- URL: [production URL]

- Supported browsers: Chrome, Firefox, Safari, Edge

- Mobile: [responsive / PWA / not supported]

### Logging In

[Screenshot of login page + steps]

### Your First 5 Minutes

1. [First thing to do after logging in]

2. [Second thing — the quick win]

3. [Third thing — explore the main feature]

Navigation Guide (standard+):

## Navigation

### Sidebar

[Screenshot with annotations describing each section]

### Quick Actions

- **Cmd+K**: Quick switcher — jump to any page or record

- **Cmd+N**: Create new [item]

[Other shortcuts]

### Breadcrumbs / Back Navigation

[How to navigate back, where breadcrumbs appear]

Keyboard Shortcuts Reference (thorough+):

## Keyboard Shortcuts

| Shortcut | Action |

|----------|--------|

| Cmd+K | Quick switcher |

| Cmd+N | New [item] |

| Cmd+S | Save |

| Escape | Close dialog / cancel |

Troubleshooting (thorough+):

## Troubleshooting

### [Error message or symptom]

**What it means**: [explanation]

**How to fix**: [steps]

### Common Questions

[FAQ generated from what would confuse a new user — based on the documentation process itself]

Admin Guide (exhaustive):

## Admin Guide

### User Management

[How to invite users, set roles, remove access]

### Settings Reference

| Setting | What it does | Default | Recommendation |

[Every setting documented]

### Data Management

[Export, import, backup, delete account]

5. Output Formats

Markdown (default): docs/USER_GUIDE.md

• Relative image paths: ![alt](screenshots/NN-description.png)

• GitHub-flavoured markdown — renders on GitHub, in VS Code, in Obsidian

HTML (exhaustive depth, or on request): docs/user-guide.html

• Single self-contained HTML file with Tailwind CDN

• Screenshots as relative paths (not base64 — keeps file size sane)

• Table of contents sidebar with smooth scroll

• Print-friendly CSS (@media print)

• Dark mode support

Screenshot naming: docs/screenshots/NN-section-description.png

• Numbers for sort order: 01-, 02-, 03-

• Section prefix: 01-dashboard-, 05-clients-, 12-settings-

• Descriptive suffix: -overview.png, -add-form.png, -saved-confirmation.png

6. Mockups and Diagrams

Mix screenshots with diagrams where it helps understanding:

Workflow diagrams (text-based, no external tools):

### How a Client Moves Through the System

New Enquiry → Create Client → Add Policy → Send Renewal → Archive

↓ ↓ ↓ ↓ ↓

[Email] [Client Page] [Policy Page] [Email Outbox] [Archive]

Annotated screenshots: When a screenshot needs callouts, describe them in the text:

![Dashboard](screenshots/01-dashboard.png)

The dashboard shows:

- **A** (top left): Your client count and active policies

- **B** (centre): Items needing attention today

- **C** (right): Recent activity feed

UI element reference: For complex pages, a labelled diagram helps:

### Editor Layout

| Area | What it does |

|------|-------------|

| Left panel | Folder tree — organise your notes |

| Centre panel | Note list — shows notes in the selected folder |

| Right panel | Editor — write and preview your note |

| Top bar | Navigation, search (Cmd+K), and view toggles |

Screenshot Quality

• Resolution: 1280x720 (desktop), 375x812 (mobile)

• Data: Realistic data. Not "Test" or "Lorem ipsum". Use the app as it would actually be used.

• Timing: Wait for data to load. No spinners, no skeleton screens in final shots.

• State: Show the page in a useful state — with data populated, relevant section expanded, key feature visible

• Consistency: Same viewport size, same zoom level, same browser throughout

• Dark mode: If documenting dark mode, switch BEFORE taking screenshots — don't mix modes in one section

Autonomy Rules

• Just do it: Navigate pages, take screenshots, read page content, write documentation

• Brief confirmation: Before writing large doc files

• Ask first: Before submitting forms with real data, before clicking delete

• Thorough/exhaustive mode: Skip confirmation for writing files and filling forms with test data

Quality Bar

The documentation should be good enough that:

• A new user can complete any task by following the guide without asking for help

• Every screenshot has context — what am I looking at? What should I do?

• Steps are atomic — one action per numbered step, never "click X and then fill in Y and Z"

• Tips reveal hidden value — shortcuts, power features, things the user wouldn't discover on their own

• Troubleshooting is real — based on actual confusing moments encountered during documentation, not hypothetical FAQs

• It's scannable — headings, screenshots, tables, tips. Nobody reads documentation top-to-bottom. They search for what they need.