Skip to content

vt-c-user-manual-generate

Generate a complete MkDocs user manual from an existing PRD. Creates one page per feature with step-by-step usage, states, edge cases, and screenshot placeholders. Serves as developer onboarding tool and human-readable test script.

Plugin: core-standards
Category: Other
Command: /vt-c-user-manual-generate

/vt-c-user-manual-generate — User Manual from PRD

Generate a complete, buildable MkDocs user manual from an existing PRD.

The manual serves three audiences: 1. Developers — human-readable test script for verifying implementations 2. Customers — product documentation alongside the prototype 3. Stakeholders — high-level overview plus detailed feature docs

When to Use

  • After /vt-c-pd-2-prd completes and a PRD exists
  • After /vt-c-pd-6-handoff to give developers a single onboarding resource
  • Anytime a PRD exists but docs/user-manual/ does not

Prerequisites

  • A PRD file exists (default: 03-PRD/PRD.md)
  • The PRD has a feature table (typically Section 4)

Invocation

/vt-c-user-manual-generate                    # Uses 03-PRD/PRD.md
/vt-c-user-manual-generate path/to/PRD.md     # Custom PRD path

Execution

Step 1: Locate and Read PRD

  1. If argument provided, use that path. Otherwise default to 03-PRD/PRD.md.
  2. If file not found, search for PRD.md in common locations:
  3. 03-PRD/PRD.md
  4. PRD.md (project root)
  5. docs/PRD.md
  6. If still not found, ask the user via AskUserQuestion.
  7. Read the full PRD file.
  8. Also read 03-PRD/PID.md if it exists (optional — technical constraints for developer notes).

Display: 

PRD found: 03-PRD/PRD.md
PID found: 03-PRD/PID.md (technical notes will be included)

Step 2: Extract Content from PRD

Parse the PRD to extract the building blocks for the manual:

2a: Project Overview (Section 1)

Extract: - Project name - Business goals / value proposition - Target timeline (if mentioned)

These become docs/index.md content.

2b: Target Users / Personas (Section 3)

Extract: - Persona names and descriptions - Primary user journeys / workflows

These map to the "Who uses this" section in each feature page and to docs/getting-started.md.

2c: Feature Table (Section 4 — Critical)

Parse the markdown feature table. Handle: - Variable column names (Feature-Name, Funktionalität, Feature, etc.) - Variable column counts (5-7 columns typical) - Priorities: Must-Have → P0, Should-Have → P1, Nice-to-Have → P2

For each feature row, extract: - Feature name → page filename (slugified) and H1 title - Description → Overview section - Priority → ordering (P0 features first) - Prototype link (if column exists) → screenshot placeholder with link

Display extraction summary: 

Extracted N features from PRD:

| # | Feature | Priority | Page |
|---|---------|----------|------|
| 1 | User Registration | P0 | features/user-registration.md |
| 2 | Dashboard | P1 | features/dashboard.md |
| ... | | | |

Use AskUserQuestion to confirm: - Looks good, generate manual → proceed - I need to adjust → let user correct before generating

2d: User Stories and Acceptance Criteria

For each feature, scan the PRD for: - User stories ("As a [role], I want [action] so that [benefit]") - Acceptance criteria (Given/When/Then) - Step-by-step flows or user journeys

These become the "How it works" sections in feature pages.

2e: Edge Cases and Risks (Sections 8, 10)

Extract: - Non-functional requirements → technical notes - Known risks and open questions → "Known limitations" section - Error scenarios → edge case table in feature pages

Step 3: Check Existing Manual

  1. Check if docs/user-manual/ already exists.
  2. If it exists: 
    docs/user-manual/ already exists with N feature pages.
    Use AskUserQuestion:
  3. Regenerate all pages — overwrite existing content with fresh generation
  4. Generate missing pages only — skip features that already have pages

  5. Cancel — exit without changes

  6. If it does not exist: proceed to Step 4.

Step 4: Generate MkDocs Configuration

Create docs/user-manual/mkdocs.yml:

site_name: "[Project Name] — User Manual"
site_description: "User manual for [Project Name]"

theme:
  name: material
  language: en
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: deep orange
      accent: orange
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: deep orange
      accent: orange
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - toc.follow

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
  - tables
  - toc:
      permalink: true

Replace [Project Name] with the actual project name from the PRD.

Create docs/user-manual/requirements-docs.txt:

mkdocs-material>=9.5
pymdown-extensions>=10.0

Step 5: Generate Index Page

Create docs/user-manual/docs/index.md:

# [Project Name]

[2-3 sentence overview from PRD Section 1 — what the product does and who it's for]

## Features

| Feature | Description | Priority |
|---------|-------------|----------|
| [Feature 1](features/feature-1-slug.md) | [brief description] | Must-Have |
| [Feature 2](features/feature-2-slug.md) | [brief description] | Should-Have |
| ... | | |

## Getting Started

New to [Project Name]? Start with the [Getting Started Guide](getting-started.md).

## For Developers

This manual doubles as a **human-readable test script**. For each feature:
1. Read the "How it works" section
2. Follow the steps in your running application
3. Verify the "Expected result" matches what you see
4. Check the "States and edge cases" table for additional scenarios

If a feature works differently from what this manual describes, either the implementation or the manual needs updating.

Step 6: Generate Getting Started Page

Create docs/user-manual/docs/getting-started.md:

# Getting Started

## What is [Project Name]?

[Expanded overview from PRD Section 1 — problem being solved, value proposition]

## Who is this for?

[List personas from PRD Section 3 with brief descriptions]

## Your First Steps

[Primary user journey from PRD Section 3 — step-by-step walkthrough of the most common flow]

### Step 1: [First action]
[Instructions derived from the primary user journey]

### Step 2: [Next action]
...

## What's Next?

Once you're comfortable with the basics, explore individual features:

[List of feature links organized by priority — P0 features first]

Step 7: Generate Feature Pages

For each feature extracted in Step 2c, create docs/user-manual/docs/features/[feature-slug].md:

# [Feature Name]

## Overview

[2-3 sentence description from PRD feature table]

## Who uses this

[Target persona/user role — mapped from PRD Section 3 personas to this feature]

## How it works

### [Step 1 title]

[Step-by-step instruction derived from user stories or acceptance criteria]

**Expected result:** [what the user should see after this step]

### [Step 2 title]

[Next step in the flow]

**Expected result:** [what happens next]

## States and edge cases

| State | What happens |
|-------|-------------|
| Normal flow | [Expected behavior when everything works] |
| [Error state 1] | [What the user sees, how to recover] |
| [Edge case 1] | [How the system handles it] |
| Empty state | [What the user sees when no data exists yet] |

## Screenshots

<!-- TODO: Add screenshots from prototype or running application -->
<!-- After prototype: capture key screens showing this feature in action -->

Content generation guidelines: - Derive step-by-step instructions from user stories and acceptance criteria - Convert Given/When/Then acceptance criteria into user-facing steps - If no user stories exist for a feature, generate reasonable steps from the description - Mark any sections where content was inferred (not directly from PRD) with <!-- Generated from PRD description — review for accuracy --> - Sort features by priority (P0 first, then P1, then P2)

Step 8: Generate Navigation

Create docs/user-manual/docs/.pages (if using mkdocs-awesome-pages) or update mkdocs.yml nav:

Add nav section to mkdocs.yml:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Features:
    - [Feature 1 Name]: features/feature-1-slug.md
    - [Feature 2 Name]: features/feature-2-slug.md
    - ...

Order features by priority (P0 first).

Step 9: Validate Build

Run a quick validation:

cd docs/user-manual && python3 -m mkdocs build --strict -d /tmp/user-manual-test 2>&1
  • If build succeeds: report success
  • If build fails (likely missing mkdocs-material): report the error but don't block — the user may not have mkdocs installed locally
  • If python3 or mkdocs not available: skip validation, report that manual validation is recommended

Step 10: Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
User Manual Generated
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Location: docs/user-manual/
Pages generated: N feature pages + index + getting-started
Source PRD: 03-PRD/PRD.md

Structure:
  docs/user-manual/
  ├── mkdocs.yml
  ├── requirements-docs.txt
  └── docs/
      ├── index.md
      ├── getting-started.md
      └── features/
          ├── feature-1.md
          ├── feature-2.md
          └── ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT STEPS:
• Review generated pages for accuracy
• Add screenshots from prototype
• Serve locally: cd docs/user-manual && mkdocs serve
• Continue workflow: /vt-c-pd-3-prototype or /vt-c-pd-6-handoff
• After spec completion: /vt-c-user-manual-update (SPEC-091)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 11: Open Brain Capture (optional)

If capture_thought MCP tool is available:

capture_thought: "User manual generated for [Project Name] from PRD. N feature pages created at docs/user-manual/. Features: [list]. Manual serves as developer onboarding tool and human-readable test script."

If not available: skip silently.

Edge Cases

ID Scenario Handling
EC-1 PRD has no feature table Ask user to identify the features section; fall back to H2 headings as features
EC-2 Feature table has non-standard columns Use fuzzy matching on column headers (Name/Feature/Funktionalität → name, Beschreibung/Description → description)
EC-3 PRD is in German Generate manual in the same language as the PRD
EC-4 docs/user-manual/ already exists with content Offer: regenerate all, generate missing only, or cancel (Step 3)
EC-5 No user stories in PRD Generate reasonable step-by-step flows from feature descriptions; mark as <!-- Generated — review for accuracy -->
EC-6 PID does not exist Skip technical notes sections; no error
EC-7 PRD has no personas section Use generic "Users" as persona; note in output
EC-8 Very large PRD (>1000 lines) Process section by section; don't try to hold entire PRD in context at once

Integration Points

Skill Relationship
/vt-c-pd-2-prd Prompts "Generate user manual?" after PRD completion
/vt-c-pd-6-handoff Includes manual link in handoff package
/vt-c-1-bootstrap Scaffolds empty docs/user-manual/ structure (this skill fills it)
/vt-c-specs-from-prd Adds docs_page field to generated specs when manual exists
/vt-c-user-manual-update Updates manual pages after spec completion (SPEC-091)
/vt-c-4-review Checks documentation completeness (Medium severity)
/vt-c-5-finalize Runs mkdocs build --strict as quality gate (SPEC-092)