Skip to content

Tutorial (30 Minutes)

Tutorial: Complete Documentation Workflow (30 Minutes)

This comprehensive tutorial walks you through setting up and running your first automated documentation workflow. By the end, you'll have a complete understanding of how Prodigy maintains documentation automatically.

What You'll Accomplish

By the end of this tutorial, you'll have: - Configured the automated documentation system for your project - Run the workflow to detect and fix documentation drift - Generated or updated an mdBook with accurate, code-grounded documentation - Understood all three phases: setup, map, and reduce

Prerequisites

Before starting, ensure you have installed Prodigy and the required tools: - Prodigy (via cargo install prodigy) - Claude Code CLI - mdBook (for building documentation) - Git (initialized repository)

If you haven't installed these yet, visit the Installation guide first

Step 1: Initialize Your Book Structure

If you don't already have an mdBook, create one:

# Create book directory and initialize
mkdir book
cd book
mdbook init

# This creates:
# book/
#   ├── book.toml
#   └── src/
#       ├── SUMMARY.md
#       └── chapter_1.md

Source: Standard mdBook initialization pattern

Step 2: Create Book Configuration

Create .prodigy/book-config.json at your project root with your project details:

{
  "project_name": "YourProject",
  "project_type": "cli_tool",
  "book_dir": "book",
  "book_src": "book/src",
  "book_build_dir": "book/book",
  "analysis_targets": [
    {
      "area": "workflow_basics",
      "source_files": [
        "src/config/workflow.rs",
        "src/workflow/executor.rs"
      ],
      "feature_categories": [
        "structure",
        "execution_model",
        "commit_tracking"
      ]
    }
  ],
  "chapter_file": "workflows/data/your-project-chapters.json",
  "custom_analysis": {
    "include_examples": true,
    "include_best_practices": true,
    "include_troubleshooting": true
  }
}

Source: Extracted from .prodigy/book-config.json structure (lines 1-219)

Key Fields Explained: - project_name - Display name for your project - book_dir - Root directory for your mdBook - analysis_targets - Areas of your codebase to analyze for documentation - area - Logical grouping name - source_files - Files to analyze for this area - feature_categories - Types of features to extract - chapter_file - Path to chapter definitions JSON

Step 3: Define Chapter Structure

Create workflows/data/your-project-chapters.json to define your documentation structure:

{
  "chapters": [
    {
      "id": "getting-started",
      "title": "Getting Started",
      "file": "getting-started.md",
      "topics": ["Installation", "Quick Start"],
      "feature_mapping": ["installation", "basic_usage"],
      "validation": "Check getting started guide matches current setup"
    },
    {
      "id": "advanced",
      "title": "Advanced Features",
      "file": "advanced/index.md",
      "topics": ["Configuration", "API Reference"],
      "feature_mapping": ["configuration", "api"],
      "validation": "Verify advanced features are documented"
    }
  ]
}

Source: Based on workflows/data/prodigy-chapters.json structure pattern

Step 4: Create the Workflow File

Create workflows/book-docs-drift.yml:

name: your-project-book-docs-drift-detection
mode: mapreduce

env:
  PROJECT_NAME: "YourProject"
  PROJECT_CONFIG: ".prodigy/book-config.json"
  FEATURES_PATH: ".prodigy/book-analysis/features.json"
  BOOK_DIR: "book"
  ANALYSIS_DIR: ".prodigy/book-analysis"
  CHAPTERS_FILE: "workflows/data/your-project-chapters.json"
  MAX_PARALLEL: "3"

setup:
  - shell: "mkdir -p $ANALYSIS_DIR"
  - claude: "/prodigy-analyze-features-for-book --project $PROJECT_NAME --config $PROJECT_CONFIG"
  - claude: "/prodigy-detect-documentation-gaps --project $PROJECT_NAME --config $PROJECT_CONFIG --features $FEATURES_PATH --chapters $CHAPTERS_FILE --book-dir $BOOK_DIR"

map:
  input: "${ANALYSIS_DIR}/flattened-items.json"
  json_path: "$[*]"

  agent_template:
    - claude: "/prodigy-analyze-subsection-drift --project $PROJECT_NAME --json '${item}' --features $FEATURES_PATH"
      commit_required: true

    - claude: "/prodigy-fix-subsection-drift --project $PROJECT_NAME --json '${item}'"
      commit_required: true
      validate:
        claude: "/prodigy-validate-doc-fix --project $PROJECT_NAME --json '${item}' --output .prodigy/validation-result.json"
        result_file: ".prodigy/validation-result.json"
        threshold: 100
        on_incomplete:
          claude: "/prodigy-complete-doc-fix --project $PROJECT_NAME --json '${item}' --gaps ${validation.gaps}"
          max_attempts: 3
          fail_workflow: false
          commit_required: true

  max_parallel: ${MAX_PARALLEL}

reduce:
  - shell: "cd book && mdbook build"
    on_failure:
      claude: "/prodigy-fix-book-build-errors --project $PROJECT_NAME"
      commit_required: true

  - shell: "rm -rf ${ANALYSIS_DIR}"
  - shell: "git add -A && git commit -m 'chore: remove temporary book analysis files' || true"

error_policy:
  on_item_failure: dlq
  continue_on_failure: true
  max_failures: 2
  error_collection: aggregate

merge:
  commands:
    - shell: "git fetch origin"
    - claude: "/prodigy-merge-master --project ${PROJECT_NAME}"
    - claude: "/prodigy-merge-worktree ${merge.source_branch} ${merge.target_branch}"

Source: Adapted from workflows/book-docs-drift.yml (lines 1-101)

Step 5: Run the Workflow

Execute the documentation workflow:

# Run with verbose output to see progress
prodigy run workflows/book-docs-drift.yml -v

What Happens During Execution:

Setup Phase (runs in parent worktree): 

✓ Creating analysis directory
✓ Analyzing codebase features → .prodigy/book-analysis/features.json
✓ Detecting documentation gaps → .prodigy/book-analysis/flattened-items.json

Map Phase (parallel agents, each in isolated worktree): 

Agent 1: Analyzing chapter 'Getting Started'
  ✓ Drift analysis complete → drift report
  ✓ Fixing outdated examples
  ✓ Validation: 100% complete
  ✓ Merged to parent worktree

Agent 2: Analyzing chapter 'Advanced Features'
  ✓ Drift analysis complete → drift report
  ✓ Adding missing configuration docs
  ✓ Validation: 100% complete
  ✓ Merged to parent worktree

Reduce Phase (runs in parent worktree): 

✓ Building book with mdbook
✓ Cleaning up temporary files
✓ Ready to merge to master

Source: Execution flow based on MapReduce workflow phases in workflows/book-docs-drift.yml and features.json analysis

Step 6: Review and Merge Changes

After the workflow completes, you'll see:

Workflow completed successfully!

Merge session-abc123 to master? [Y/n]

Before merging, review the changes:

# Check what was modified
cd ~/.prodigy/worktrees/your-project/session-abc123/
git log --oneline
git diff master

# Review specific chapter changes
git show HEAD:book/src/getting-started.md

Type Y to merge changes back to your original branch.

Step 7: Verify the Updated Documentation

After merging, view your updated documentation:

# Build and serve locally
cd book
mdbook serve --open

# Your browser opens to http://localhost:3000
# Navigate through chapters to see updated content

Expected Results: - ✓ All code examples reference actual source files - ✓ Configuration examples match your codebase types - ✓ API documentation reflects current function signatures - ✓ Outdated sections updated or removed - ✓ Cross-references between chapters are valid

Understanding the Workflow Phases

The automated documentation workflow uses Prodigy's MapReduce pattern with three phases:

Setup Phase

Purpose: Analyze your codebase and prepare work items

Commands: 1. mkdir -p $ANALYSIS_DIR - Create temporary analysis directory 2. /prodigy-analyze-features-for-book - Extract features from source files into features.json 3. /prodigy-detect-documentation-gaps - Compare features to chapters, create flattened-items.json

Output: JSON file with list of chapters/subsections to process

Source: Setup phase from workflows/book-docs-drift.yml:24-34

Map Phase

Purpose: Process each chapter/subsection in parallel to detect and fix drift

For each chapter: 1. /prodigy-analyze-subsection-drift - Compare chapter to codebase, identify outdated/missing content 2. /prodigy-fix-subsection-drift - Update markdown file with accurate, grounded examples 3. Validation - Ensure documentation meets quality standards (100% threshold) 4. Gap filling - If validation fails, run completion attempts (max 3)

Parallelism: Configured via max_parallel: 3 - three chapters processed simultaneously

Isolation: Each chapter processed in its own git worktree, merged back to parent automatically

Source: Map phase from workflows/book-docs-drift.yml:37-59

Reduce Phase

Purpose: Validate the complete book and clean up

Commands: 1. mdbook build - Compile the book to catch broken links or formatting errors 2. /prodigy-fix-book-build-errors - Fix any build errors (only runs if build fails) 3. Cleanup temporary analysis files

Source: Reduce phase from workflows/book-docs-drift.yml:62-69

Customization Tips

Adjust Parallelism: 

env:
  MAX_PARALLEL: "5"  # Process 5 chapters at once (default: 3)

Focus on Specific Areas: Edit .prodigy/book-config.json to analyze only certain parts of your codebase: 

{
  "analysis_targets": [
    {
      "area": "api",
      "source_files": ["src/api/**/*.rs"],
      "feature_categories": ["endpoints", "authentication"]
    }
  ]
}

Change Validation Threshold: 

validate:
  threshold: 95  # Allow 95% instead of 100%

Troubleshooting

Issue: "Claude command not found" - Solution: Ensure Claude Code CLI is installed and in your PATH - Verify: claude --version

Issue: "features.json not generated" - Cause: Setup phase failed to analyze codebase - Solution: Check that source_files in book-config.json exist and are valid - Debug: Run with -vv for detailed logs

Issue: "mdbook build fails with broken links" - Cause: Cross-references to non-existent chapters - Solution: The workflow automatically fixes this in reduce phase - Manual fix: Check book/src/SUMMARY.md for invalid links

Issue: "Validation threshold not met" - Cause: Documentation doesn't meet 100% quality standard - Solution: The on_incomplete handler attempts to complete gaps (max 3 attempts) - If still incomplete: Review .prodigy/validation-result.json for details

Source: Common issues from features.json troubleshooting section (lines 802-885)

Next Steps

Now that you have automated documentation working, explore:

What You've Learned

✓ How to configure automated documentation for any project ✓ The structure of a MapReduce documentation workflow ✓ How setup/map/reduce phases process your codebase ✓ How to review and merge documentation updates ✓ Basic troubleshooting techniques

Time Investment Breakdown

  • Prerequisites setup: 5-10 minutes (one-time)
  • Configuration files: 10 minutes
  • First workflow run: 5-10 minutes (depending on project size)
  • Review and merge: 5 minutes

Total: 25-35 minutes for your first complete run