ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/expansion-packs/bmad-technical-writing/docs/README.md

10 KiB
Raw Blame History

Technical Writing Expansion Pack - Documentation

Welcome to the complete documentation suite for the BMad Technical Writing Expansion Pack. This guide will help you master AI-powered technical book authoring from concept to published book.

📚 Documentation Map

🚀 Getting Started

Start here if you're new to the Technical Writing Expansion Pack:

  • Quick Reference Card ⚡ 5 minutes

    • One-page cheat sheet with most common workflows, agents, and commands
    • Perfect for quick lookups while writing
    • Print-friendly format

  • Getting Started Tutorial 🎓 1-2 hours

    • Hands-on walkthrough: Write your first chapter
    • Uses real example: "Python Data Structures Handbook"
    • Complete workflow from planning to publishing
    • START HERE for hands-on learning

  • User Guide 📖 60-90 minutes

    • Conceptual overview of the entire system
    • Understanding agents, workflows, and templates
    • Architecture and design principles
    • Greenfield vs brownfield approaches

🔄 Core Guides

Deep-dive documentation for understanding how everything works:

  • Process Flows 📊 30-45 minutes

    • Visual Mermaid diagrams for all 15 workflows
    • Book authoring lifecycle diagram
    • Agent collaboration maps
    • Publishing decision trees
    • Great for visual learners

  • Integration Guide 🔗 15-20 minutes

    • Using Technical Writing pack with BMad core
    • Multi-expansion usage patterns
    • Git integration best practices
    • CI/CD for code examples

📑 Reference Documentation

Comprehensive reference for all system components:

  • Agent Reference 🤖 45-60 minutes

    • All 13 agents documented in detail
    • Purpose, commands, dependencies, examples
    • Agent categories and selection guide
    • Integration patterns

  • Workflow Guide 🔀 30-45 minutes

    • All 15 workflows explained
    • When to use each workflow
    • Inputs, outputs, time estimates
    • Workflow decision tree

  • Template Gallery 📝 40-50 minutes

    • All 18 templates with examples
    • Sample filled outputs
    • Usage guidance
    • Customization tips

  • Task Reference ✅ 25-35 minutes

    • All 33 tasks organized by phase
    • Purpose, prerequisites, time estimates
    • Quick reference table

  • Checklist Reference ☑️ 25-30 minutes

    • All 31 checklists organized by phase
    • Quality gate recommendations
    • Checklist roadmap

🛠️ Support Documentation

Get help when you need it:

  • Troubleshooting Guide 🔧 As needed

    • Common installation issues
    • Agent activation problems
    • Workflow execution errors
    • Build/validation fixes

  • FAQ ❓ As needed

    • 25-30 frequently asked questions
    • Quick answers to common questions
    • Organized by category

📦 Examples

Real-world examples showing complete outputs:

🎯 Recommended Reading Order

For Beginners (First Time Users)

Time Investment: 2-3 hours to productivity

  1. Quick Reference Card ⚡ 5 min

    • Get oriented with one-page overview
    • Understand core commands

  2. Getting Started Tutorial 🎓 1-2 hrs

    • Hands-on: Write your first section
    • Learn by doing with real example
    • Most important for beginners!

  3. User Guide 📖 60-90 min

    • Understand conceptual foundations
    • Learn system architecture
    • Grasp key concepts

  4. Start Writing! 📝

    • Apply what you've learned
    • Refer to Quick Reference as needed
    • Use Troubleshooting when stuck

For Intermediate Users (Have Written 1-2 Chapters)

Goal: Master all workflows and optimize your process

  1. Workflow Guide 🔀 30-45 min

    • Understand all 15 workflows in depth
    • Choose optimal workflows for your use case
    • Learn workflow decision criteria

  2. Agent Reference 🤖 45-60 min

    • Master all 13 agents
    • Understand agent collaboration
    • Learn advanced agent usage

  3. Process Flows 📊 30-45 min

    • Visualize workflow orchestration
    • Understand agent handoffs
    • Optimize your workflow

  4. Template Gallery 📝 40-50 min

    • See all template outputs
    • Learn template customization
    • Understand template usage patterns

For Advanced Users (Scaling to Full Books)

Goal: Customize, optimize, and scale your book production

  1. Integration Guide 🔗 15-20 min

    • Multi-expansion usage
    • CI/CD integration
    • Git workflow optimization

  2. Task Reference ✅ 25-35 min

    • Understand all 33 tasks
    • Customize task workflows
    • Build your own processes

  3. Checklist Reference ☑️ 25-30 min

    • Master all quality gates
    • Customize checklists
    • Define your own standards

  4. Examples 📦

    • Study complete examples
    • Understand output quality
    • Model your work after examples

🛤️ Learning Paths

Choose the path that matches your goal:

Path 1: Greenfield Book (New Book from Scratch)

Recommended Documentation:

  1. Getting Started Tutorial - Learn the basics
  2. Workflow Guide - Focus on greenfield workflows
  3. Process Flows - See book-planning and section-development flows
  4. Agent Reference - Master core agents (skip Book Analyst)

Workflows You'll Use:

  • book-planning-workflow
  • section-planning-workflow
  • section-development-workflow
  • chapter-assembly-workflow
  • packtpub-submission-workflow (or your publisher)

Path 2: Brownfield Book (Existing Book Updates)

Recommended Documentation:

  1. User Guide - Understand brownfield approach
  2. Agent Reference - Focus on Book Analyst agent
  3. Workflow Guide - Focus on brownfield workflows
  4. Process Flows - See edition-update and add-chapter flows

Workflows You'll Use:

  • book-edition-update-workflow
  • add-chapter-to-existing-book-workflow
  • incorporate-review-feedback-workflow
  • section-development-workflow (for new/updated content)

Path 3: Self-Publishing (Leanpub/KDP/Gumroad)

Recommended Documentation:

  1. Getting Started Tutorial - Learn core process
  2. Workflow Guide - Focus on self-publishing-workflow
  3. FAQ - Self-publishing specific questions
  4. Process Flows - See self-publishing flow diagram

Workflows You'll Use:

  • book-planning-workflow
  • section-development-workflow
  • chapter-assembly-workflow
  • self-publishing-workflow

Path 4: Traditional Publishing (PacktPub/O'Reilly/Manning)

Recommended Documentation:

  1. Getting Started Tutorial - Learn core process
  2. Workflow Guide - Focus on publisher-specific workflows
  3. Checklist Reference - Publisher-specific checklists
  4. Process Flows - See publisher submission flows

Workflows You'll Use:

  • book-planning-workflow
  • section-development-workflow
  • chapter-assembly-workflow
  • packtpub-submission-workflow / oreilly-submission-workflow / manning-meap-workflow

🆘 Getting Help

Quick Answers

Problem Solving

  • Troubleshooting Guide - Common issues and solutions
  • Organized by category (installation, agents, workflows, templates, build)

Community Support

📊 Documentation Statistics

Total Documentation: 13 guides + 4 examples = 17 documents

Coverage:

  • ✅ 13 agents documented
  • ✅ 15 workflows explained
  • ✅ 18 templates showcased
  • ✅ 33 tasks referenced
  • ✅ 31 checklists detailed

Word Count: ~35,000+ words of comprehensive documentation

Time to Read Everything: ~10-12 hours (not required - read what you need!)

Time to Productivity: ~2-3 hours (Quick Reference + Getting Started Tutorial + User Guide)

🎓 Documentation Maintenance

This documentation is kept up-to-date with each expansion pack release.

Current Version: v1.1.0 Last Updated: 2024 Maintained By: BMad Team Community Contributions: Welcome! Submit PRs for improvements

Version History:

  • v1.1.0 - Complete documentation suite (Sprint 5+)
  • v1.0.0 - Initial release with basic README

🔖 Bookmark This Page

Save this documentation index for easy access to all guides. You'll reference it frequently while writing your technical book.

✨ Ready to Start?

Absolute Beginners

→ Quick Reference then Getting Started Tutorial

Want Deep Understanding

→ User Guide then Process Flows

Need Specific Info

→ Use search (Ctrl+F) on this page to find relevant guide

Have Questions

→ FAQ or Discord Community

Happy Writing! 📚✨

Your journey to published technical book starts here.

Documentation Index - Technical Writing Expansion Pack v1.1.0 Part of BMad-Method™ - The Universal AI Agent Framework