BMAD-METHOD/expansion-packs/bmad-technical-writing/docs

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:

• Example Book Outline

  • "Python Data Structures Handbook" complete outline
  • Shows book-outline-tmpl output

• Example Chapter Outline

  • Chapter 3: Lists and Tuples
  • Section breakdown and structure

• Example Section Plan

  • Section 3.2: List Operations
  • Detailed planning for one section

• Example Complete Chapter

  • Chapter 1: Introduction to Python Data Structures
  • Full chapter showing workflow results

---

🎯 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

• FAQ - 25-30 common questions with quick answers
• Quick Reference - Command cheat sheet

Problem Solving

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

Community Support

• Discord Community - Ask questions, share experiences
• GitHub Discussions - Technical discussions
• GitHub Issues - Report bugs, request features

---

📊 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: ~30,000+ words of comprehensive documentation

Time to Read Everything: ~8-10 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