351 lines
10 KiB
Markdown
351 lines
10 KiB
Markdown
# 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](quick-reference.md)** ⚡ *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](getting-started.md)** 🎓 *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](user-guide.md)** 📖 *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](process-flows.md)** 📊 *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](integration-guide.md)** 🔗 *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](agent-reference.md)** 🤖 *45-60 minutes*
|
|
- All 13 agents documented in detail
|
|
- Purpose, commands, dependencies, examples
|
|
- Agent categories and selection guide
|
|
- Integration patterns
|
|
|
|
- **[Workflow Guide](workflow-guide.md)** 🔀 *30-45 minutes*
|
|
- All 15 workflows explained
|
|
- When to use each workflow
|
|
- Inputs, outputs, time estimates
|
|
- Workflow decision tree
|
|
|
|
- **[Template Gallery](template-gallery.md)** 📝 *40-50 minutes*
|
|
- All 18 templates with examples
|
|
- Sample filled outputs
|
|
- Usage guidance
|
|
- Customization tips
|
|
|
|
- **[Task Reference](task-reference.md)** ✅ *25-35 minutes*
|
|
- All 33 tasks organized by phase
|
|
- Purpose, prerequisites, time estimates
|
|
- Quick reference table
|
|
|
|
- **[Checklist Reference](checklist-reference.md)** ☑️ *25-30 minutes*
|
|
- All 31 checklists organized by phase
|
|
- Quality gate recommendations
|
|
- Checklist roadmap
|
|
|
|
---
|
|
|
|
### 🛠️ Support Documentation
|
|
|
|
Get help when you need it:
|
|
|
|
- **[Troubleshooting Guide](troubleshooting.md)** 🔧 *As needed*
|
|
- Common installation issues
|
|
- Agent activation problems
|
|
- Workflow execution errors
|
|
- Build/validation fixes
|
|
|
|
- **[FAQ](faq.md)** ❓ *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](examples/book-outline-example.md)**
|
|
- "Python Data Structures Handbook" complete outline
|
|
- Shows book-outline-tmpl output
|
|
|
|
- **[Example Chapter Outline](examples/chapter-outline-example.md)**
|
|
- Chapter 3: Lists and Tuples
|
|
- Section breakdown and structure
|
|
|
|
- **[Example Section Plan](examples/section-plan-example.md)**
|
|
- Section 3.2: List Operations
|
|
- Detailed planning for one section
|
|
|
|
- **[Example Complete Chapter](examples/complete-chapter-example.md)**
|
|
- 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](quick-reference.md)** ⚡ *5 min*
|
|
- Get oriented with one-page overview
|
|
- Understand core commands
|
|
|
|
2. **[Getting Started Tutorial](getting-started.md)** 🎓 *1-2 hrs*
|
|
- Hands-on: Write your first section
|
|
- Learn by doing with real example
|
|
- **Most important for beginners!**
|
|
|
|
3. **[User Guide](user-guide.md)** 📖 *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](workflow-guide.md)** 🔀 *30-45 min*
|
|
- Understand all 15 workflows in depth
|
|
- Choose optimal workflows for your use case
|
|
- Learn workflow decision criteria
|
|
|
|
2. **[Agent Reference](agent-reference.md)** 🤖 *45-60 min*
|
|
- Master all 13 agents
|
|
- Understand agent collaboration
|
|
- Learn advanced agent usage
|
|
|
|
3. **[Process Flows](process-flows.md)** 📊 *30-45 min*
|
|
- Visualize workflow orchestration
|
|
- Understand agent handoffs
|
|
- Optimize your workflow
|
|
|
|
4. **[Template Gallery](template-gallery.md)** 📝 *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](integration-guide.md)** 🔗 *15-20 min*
|
|
- Multi-expansion usage
|
|
- CI/CD integration
|
|
- Git workflow optimization
|
|
|
|
2. **[Task Reference](task-reference.md)** ✅ *25-35 min*
|
|
- Understand all 33 tasks
|
|
- Customize task workflows
|
|
- Build your own processes
|
|
|
|
3. **[Checklist Reference](checklist-reference.md)** ☑️ *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](getting-started.md) - Learn the basics
|
|
2. [Workflow Guide](workflow-guide.md) - Focus on greenfield workflows
|
|
3. [Process Flows](process-flows.md) - See book-planning and section-development flows
|
|
4. [Agent Reference](agent-reference.md) - 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](user-guide.md) - Understand brownfield approach
|
|
2. [Agent Reference](agent-reference.md) - Focus on Book Analyst agent
|
|
3. [Workflow Guide](workflow-guide.md) - Focus on brownfield workflows
|
|
4. [Process Flows](process-flows.md) - 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](getting-started.md) - Learn core process
|
|
2. [Workflow Guide](workflow-guide.md) - Focus on self-publishing-workflow
|
|
3. [FAQ](faq.md) - Self-publishing specific questions
|
|
4. [Process Flows](process-flows.md) - 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](getting-started.md) - Learn core process
|
|
2. [Workflow Guide](workflow-guide.md) - Focus on publisher-specific workflows
|
|
3. [Checklist Reference](checklist-reference.md) - Publisher-specific checklists
|
|
4. [Process Flows](process-flows.md) - 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](faq.md)** - 25-30 common questions with quick answers
|
|
- **[Quick Reference](quick-reference.md)** - Command cheat sheet
|
|
|
|
### Problem Solving
|
|
- **[Troubleshooting Guide](troubleshooting.md)** - Common issues and solutions
|
|
- Organized by category (installation, agents, workflows, templates, build)
|
|
|
|
### Community Support
|
|
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Ask questions, share experiences
|
|
- **[GitHub Discussions](https://github.com/bmadcode/bmad-method/discussions)** - Technical discussions
|
|
- **[GitHub Issues](https://github.com/bmadcode/bmad-method/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](quick-reference.md)** then **[Getting Started Tutorial](getting-started.md)**
|
|
|
|
### Want Deep Understanding
|
|
→ **[User Guide](user-guide.md)** then **[Process Flows](process-flows.md)**
|
|
|
|
### Need Specific Info
|
|
→ Use search (Ctrl+F) on this page to find relevant guide
|
|
|
|
### Have Questions
|
|
→ **[FAQ](faq.md)** or **[Discord Community](https://discord.gg/gk8jAdXWmj)**
|
|
|
|
---
|
|
|
|
**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*
|