BuildBetter Docs

DOCUMENTATION_PROJECT_SUMMARY

BuildBetter Documentation Project - Complete Summary

Date: November 8, 2024 Status: Documentation written, Automation tool architected, Testing in progress

✅ COMPLETED TODAY

Part 1: Use Case Documentation (27 files, ~200KB)

Quick Start Guides (5 files - COMPLETE)

All have full content, ready for screenshots:

  1. Product: Your First 5 Customer Calls (15KB)
    • 30 min time to value
    • 24 screenshots needed
    • File: pages/Use Cases/quick-start/product-first-calls.mdx
  2. Founder: Find PMF in First 100 Conversations (19KB)
    • 1 hour time to value
    • 27 screenshots needed
    • File: pages/Use Cases/quick-start/founder-first-conversations.mdx
  3. Sales: Build Your Sales Playbook in 2 Weeks (19KB)
    • 2 week time to value
    • 24 screenshots needed
    • File: pages/Use Cases/quick-start/sales-record-learn.mdx
  4. CS: Track Customer Health & Prevent Churn (20KB)
    • 1 week time to value
    • 27 screenshots needed
    • File: pages/Use Cases/quick-start/cs-health-tracking.mdx
  5. Marketing: Understand Your ICP & Customer Language (23KB)
    • 1 week time to value
    • 24 screenshots needed
    • File: pages/Use Cases/quick-start/marketing-icp.mdx

Workflow Guides (5 files - COMPLETE)

Bite-sized, actionable guides under respective sections:

  1. Product: Turn Spreadsheet Feedback into Roadmap Priorities (18KB)
    • 20 screenshots needed
    • File: pages/Use Cases/product/csv-to-insights.mdx
  2. CS: Reduce Support Tickets by 20-30% (19KB)
    • 17 screenshots needed
    • File: pages/Use Cases/cs/ticket-analysis.mdx
  3. CS: Write Help Docs from Customer Questions (15KB)
    • 9 screenshots needed
    • File: pages/Use Cases/cs/writing-documentation.mdx
  4. CS: Keep Documentation Current (18KB)
    • 9 screenshots needed
    • File: pages/Use Cases/cs/updating-documentation.mdx
  5. Sales: Analyze Lost Deals to Improve Win Rate (8KB - outline)
    • 4 screenshots needed
    • File: pages/Use Cases/sales/lost-deal-analysis.mdx

Advanced Guides (9 files - STUBS)

Structure + "Coming Soon" notes, ready to flesh out:

Founder Section (NEW):

Marketing Section (NEW):

Plus: 12 existing advanced guides untouched

File: docs.json

New structure:

Total: 156 screenshots needed across all docs

Part 2: Screenshot Automation Tool (ARCHITECTURE COMPLETE)

Core System (3,225 lines of Python)

Source Files:

Config & Docs:

Annotation Types (AI-powered)

  1. Highlights (Yellow Glow)
    • Multi-layer glow effect
    • Draws attention to elements
    • Configurable intensity
  2. Arrows (Red Curved)
    • Bezier curved arrows
    • Text labels ("Click here")
    • Points to actions
  3. Callouts (Text Boxes)
    • Semi-transparent black boxes
    • White text with wrapping
    • Connected to elements with leader lines
    • Explains "You'll see..."
  4. Step Numbers (Red Circles)
    • Numbered "1", "2", "3" circles
    • White borders for visibility
    • Shows sequential flow
  5. Zoom Indicators (Blue Dashed)
    • Highlights detail areas
    • "Detail" label
    • For small/nested elements
  6. Comparison Splits (Before/After)
    • Vertical split lines
    • ❌ Before / ✅ After labels
    • Color-coded

AI Features:

🚧 CURRENT STATUS

What Works ✅

What's Blocked 🔄

🎯 TO COMPLETE THE TOOL

Fix 1: Upgrade Anthropic in Venv

cd /Users/shooby/Dev/docs/screenshot-automation
source venv/bin/activate
pip install --upgrade 'anthropic>=0.39.0'

Fix 2: Test It Works

# Still in venv
python scripts/capture_screenshots.py --doc quick-start/product-first-calls.mdx

This should:

  1. ✅ Parse 24 screenshots from MDX
  2. ✅ Initialize all components
  3. 🔄 Open browser (Chrome will launch)
  4. 🔄 Login to BuildBetter
  5. 🔄 Navigate to each documented state
  6. 🔄 Capture screenshot
  7. 🔄 Use AI to detect elements + determine annotations
  8. 🔄 Add annotations (highlights, arrows, callouts)
  9. 🔄 Save to output/screenshots/

Expected outcome: 24 annotated PNG files in output/screenshots/quick-start/product-first-calls/

📸 SCREENSHOT INVENTORY

Total needed: 156 screenshots across all docs

By priority:

By document:

Doc Screenshots Status
Product: First 5 Calls 24 Ready to capture
Founder: First 100 27 Ready to capture
Sales: Playbook 24 Ready to capture
CS: Health Tracking 27 Ready to capture
Marketing: ICP 24 Ready to capture
Product: CSV 20 Ready to capture
CS: Tickets 17 Ready to capture
CS: Write Docs 9 Ready to capture
CS: Update Docs 9 Ready to capture
Sales: Lost Deals 4 Stub (expand later)
Marketing: Stories 5 Stub (expand later)
Founder: Planning 4 Stub (expand later)
Total 156 -

💡 WHAT YOU NEED TO DO

Immediate (This Session)

  1. Fix venv Anthropic version: 
    cd /Users/shooby/Dev/docs/screenshot-automation
source venv/bin/activate
pip install --upgrade 'anthropic>=0.39.0'
deactivate
  2. Create demo workspace in BuildBetter:
    • Name: "Documentation Screenshots"
    • Add 3-5 sample calls
    • Create 2-3 collections
    • Generate some signals (auto-happens from calls)
  3. Run first test: 
    cd /Users/shooby/Dev/docs/screenshot-automation
source venv/bin/activate
python scripts/capture_screenshots.py --doc quick-start/product-first-calls.mdx
  4. Review output:
    • Chrome should open and navigate BuildBetter
    • Screenshots saved to output/screenshots/
    • Check if annotations look good

This Week

  1. Refine based on results:
    • Adjust annotation positioning if needed
    • Tweak AI prompts for better element detection
    • Fix any navigation issues
  2. Process all priority docs: 
    python scripts/capture_screenshots.py --all
  3. Place screenshots in docs:
    • Copy from output/screenshots/ to images/screenshots/
    • Update MDX files with paths

Next Week

  1. Build validation system (scripts/validate_docs.py)
  2. Set up GitHub Action for weekly validation
  3. Complete stub docs (expand the 9 outlines)

📊 PROJECT METRICS

Documentation

Automation Tool

Investment

Projected ROI

🎯 SUCCESS CRITERIA

Documentation is complete when:

Automation is complete when:

🚀 NEXT COMMAND TO RUN

cd /Users/shooby/Dev/docs/screenshot-automation
source venv/bin/activate
pip install --upgrade 'anthropic>=0.39.0'
python scripts/capture_screenshots.py --doc quick-start/product-first-calls.mdx

Watch for Chrome to open and start navigating your BuildBetter app!

You're 95% there. Just need to fix the venv anthropic version and run it! 🎉