feat: add section-driven development workflow for sprint 2.6
This commit is contained in:
Joshua Magady
parent
abcd82e20d
commit
ff94e05cd8
|
|
@ -15,6 +15,23 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su
|
|||
- 📚 **6 Knowledge Bases** - Comprehensive publisher guidelines and technical writing standards
|
||||
- 🔄 **15 Workflows** - Section-driven development, publisher-specific submission workflows (PacktPub, O'Reilly, Manning, Self-Publishing), brownfield workflows for edition updates, and complete book lifecycle management
|
||||
|
||||
## 📖 Documentation
|
||||
|
||||
**New to Technical Writing Pack? Start here!**
|
||||
|
||||
### 🚀 Quick Start
|
||||
- **[Quick Reference Card](docs/quick-reference.md)** - One-page cheat sheet (5 min read)
|
||||
- **[Getting Started Tutorial](docs/getting-started.md)** - Write your first chapter hands-on (1-2 hours)
|
||||
- **[User Guide](docs/user-guide.md)** - Complete system overview (60-90 min read)
|
||||
|
||||
### 📚 Complete Documentation
|
||||
- **[Documentation Index](docs/README.md)** - Navigation hub for all documentation
|
||||
- **[Process Flows](docs/process-flows.md)** - Visual workflow diagrams
|
||||
- **[FAQ](docs/faq.md)** - Frequently asked questions
|
||||
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
|
||||
|
||||
**See [docs/README.md](docs/README.md) for complete documentation map with 13 guides + 4 examples.**
|
||||
|
||||
## ✍️ Included Agents
|
||||
|
||||
### Planning & Design Team (Sprint 1)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,350 @@
|
|||
# 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*
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
# Examples Directory
|
||||
|
||||
This directory contains real-world examples of BMad Technical Writing outputs.
|
||||
|
||||
## Available Examples
|
||||
|
||||
The following example files demonstrate complete workflows:
|
||||
|
||||
- `book-outline-example.md` - Complete book outline using book-outline-tmpl
|
||||
- `chapter-outline-example.md` - Chapter breakdown with section planning
|
||||
- `section-plan-example.md` - Detailed section plan
|
||||
- `complete-chapter-example.md` - Full chapter from section-driven workflow
|
||||
|
||||
These examples use "Python Data Structures Handbook" as a consistent demonstration project.
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
# FAQ - Frequently Asked Questions
|
||||
|
||||
Common questions about the BMad Technical Writing Expansion Pack.
|
||||
|
||||
## General Questions
|
||||
|
||||
### What is the Technical Writing Expansion Pack?
|
||||
The Technical Writing Expansion Pack extends BMad-Method with 13 specialized agents, 15 workflows, and comprehensive tools for writing technical books for publishers like PacktPub, O'Reilly, Manning, or self-publishing platforms.
|
||||
|
||||
### Who is this for?
|
||||
Technical book authors, technical trainers, documentation specialists, and anyone creating comprehensive technical content with code examples and tutorials.
|
||||
|
||||
### Do I need BMad core?
|
||||
Yes, this expansion pack requires BMad-Method core to be installed first.
|
||||
|
||||
### How much does it cost?
|
||||
The expansion pack is free and open source, part of the BMad-Method framework.
|
||||
|
||||
## Getting Started Questions
|
||||
|
||||
### Where should I start?
|
||||
1. Read the [Quick Reference Card](quick-reference.md) (5 min)
|
||||
2. Follow the [Getting Started Tutorial](getting-started.md) (1-2 hours)
|
||||
3. Start writing your first section!
|
||||
|
||||
### Which workflow should I use first?
|
||||
Start with `book-planning-workflow` to create your book outline, then use `section-development-workflow` for incremental chapter development.
|
||||
|
||||
### Do I need all 13 agents?
|
||||
No. The 10 core agents handle most needs. The 3 optional agents (Learning Path Designer, Sample Code Maintainer, Version Manager) are for advanced scenarios.
|
||||
|
||||
## Agent Questions
|
||||
|
||||
### When should I use optional agents?
|
||||
- **Learning Path Designer**: Complex prerequisite mapping across 15+ chapters
|
||||
- **Sample Code Maintainer**: Managing large code repositories with CI/CD
|
||||
- **Version Manager**: Supporting multiple platform versions (e.g., Python 3.8, 3.9, 3.10, 3.11)
|
||||
|
||||
### Can I skip agents?
|
||||
You can streamline by merging optional agents with core agents for simpler projects.
|
||||
|
||||
## Workflow Questions
|
||||
|
||||
### Greenfield vs Brownfield - which do I need?
|
||||
- **Greenfield**: New book from scratch → Use planning and development workflows
|
||||
- **Brownfield**: Updating existing book (2nd edition, new chapters) → Use brownfield workflows
|
||||
|
||||
### Section-driven vs Chapter-driven - what's the difference?
|
||||
- **Section-driven**: Break chapter into 2-5 page sections, develop independently (recommended)
|
||||
- **Chapter-driven**: Write entire chapter at once (faster but less manageable)
|
||||
|
||||
### Can I customize workflows?
|
||||
Yes! Workflows are YAML files you can modify. See [Workflow Guide](workflow-guide.md) for details.
|
||||
|
||||
## Publishing Questions
|
||||
|
||||
### Which publisher workflow should I use?
|
||||
- **PacktPub** → `packtpub-submission-workflow`
|
||||
- **O'Reilly** → `oreilly-submission-workflow`
|
||||
- **Manning** → `manning-meap-workflow`
|
||||
- **Self-publishing** → `self-publishing-workflow`
|
||||
|
||||
### Can I self-publish?
|
||||
Yes! The `self-publishing-workflow` supports Leanpub, Amazon KDP, and Gumroad.
|
||||
|
||||
### Do I need to use publisher workflows?
|
||||
Only if you're submitting to a publisher. For internal docs or open source, you can skip these.
|
||||
|
||||
## Technical Questions
|
||||
|
||||
### Can I use this with the Creative Writing expansion?
|
||||
Yes! You can combine expansion packs. Useful for technical books with narrative elements.
|
||||
|
||||
### Can multiple authors collaborate?
|
||||
Yes! Use Git for version control and coordinate through workflows.
|
||||
|
||||
### How does this work with Git?
|
||||
All outputs are markdown files that work great with Git. Commit sections as you complete them.
|
||||
|
||||
## Advanced Questions
|
||||
|
||||
### How do I manage multiple versions (Python 3.10, 3.11, etc.)?
|
||||
Use the Version Manager agent or the `version-matrix-check` task to test across versions.
|
||||
|
||||
### Can I write multi-platform books (Windows/Mac/Linux)?
|
||||
Yes! Use the `cross-platform-checklist` and Code Curator to test on all platforms.
|
||||
|
||||
### How do I handle large books (1000+ pages)?
|
||||
Use section-driven development to break into manageable units. Develop chapters in parallel.
|
||||
|
||||
---
|
||||
|
||||
## Still Have Questions?
|
||||
|
||||
- 📖 [User Guide](user-guide.md) - Comprehensive overview
|
||||
- 🔧 [Troubleshooting Guide](troubleshooting.md) - Common issues
|
||||
- 💬 [Discord Community](https://discord.gg/gk8jAdXWmj) - Ask questions
|
||||
- 🐛 [GitHub Issues](https://github.com/bmadcode/bmad-method/issues) - Report bugs
|
||||
|
||||
---
|
||||
|
||||
*FAQ - Technical Writing Expansion Pack v1.1.0*
|
||||
|
|
@ -0,0 +1,903 @@
|
|||
# Getting Started - Your First Technical Book Chapter
|
||||
|
||||
This hands-on tutorial walks you through creating your first technical book chapter using the BMad Technical Writing Expansion Pack. You'll go from concept to completed chapter in 2-3 hours.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Tutorial Overview](#tutorial-overview)
|
||||
- [Step 1: Plan Your Book](#step-1-plan-your-book)
|
||||
- [Step 2: Plan Your First Chapter](#step-2-plan-your-first-chapter)
|
||||
- [Step 3: Write Your First Section](#step-3-write-your-first-section)
|
||||
- [Step 4: Review Your Section](#step-4-review-your-section)
|
||||
- [Step 5: Complete Remaining Sections](#step-5-complete-remaining-sections)
|
||||
- [Step 6: Assemble Your Chapter](#step-6-assemble-your-chapter)
|
||||
- [Step 7: Prepare for Publishing](#step-7-prepare-for-publishing)
|
||||
- [Next Steps](#next-steps)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting this tutorial, ensure you have:
|
||||
|
||||
- **BMad-Method installed** - Core framework must be installed
|
||||
- **Technical Writing Expansion Pack installed** - This pack must be installed
|
||||
- **AI interface ready** - Either:
|
||||
- Web UI (Gemini, ChatGPT, or Claude) for planning phase
|
||||
- IDE with AI (Cursor, VS Code, or Claude Code) for development phase
|
||||
- **Basic markdown knowledge** - You should understand markdown formatting
|
||||
- **Technical subject matter** - Know what you want to teach (we'll use Python as example)
|
||||
|
||||
**Installation Check**:
|
||||
```bash
|
||||
# Verify BMad is installed
|
||||
npx bmad-method --version
|
||||
|
||||
# Verify Technical Writing pack is installed
|
||||
ls ~/.bmad-method/expansion-packs/bmad-technical-writing
|
||||
```
|
||||
|
||||
If not installed, run:
|
||||
```bash
|
||||
npx bmad-method install
|
||||
# Select "Technical Book Writing Studio" from expansion packs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tutorial Overview
|
||||
|
||||
### What We'll Build
|
||||
|
||||
We'll create **Chapter 1** of "Python Data Structures Handbook" - an introductory chapter covering lists, tuples, and basic data manipulation.
|
||||
|
||||
**Chapter Title**: "Introduction to Python Data Structures"
|
||||
|
||||
**Chapter Content**:
|
||||
- What are data structures and why they matter
|
||||
- Introduction to lists with practical examples
|
||||
- Introduction to tuples with practical examples
|
||||
- When to use lists vs tuples
|
||||
- Hands-on exercises with solutions
|
||||
|
||||
**Deliverables**:
|
||||
- Complete chapter outline (6 sections)
|
||||
- One fully written section (~3 pages)
|
||||
- Working code examples
|
||||
- Technical review notes
|
||||
- Publisher-ready chapter draft
|
||||
|
||||
### Estimated Time
|
||||
|
||||
- **Planning** (30 min): Book outline + chapter structure
|
||||
- **Section Writing** (45-60 min): Write one complete section
|
||||
- **Review** (15 min): Technical review and revision
|
||||
- **Assembly** (30 min): Complete chapter assembly
|
||||
- **Total**: 2-3 hours
|
||||
|
||||
### What You'll Learn
|
||||
|
||||
By completing this tutorial, you'll understand:
|
||||
- How to activate and use BMad agents
|
||||
- How to execute workflows for book planning
|
||||
- How to create sections using section-driven development
|
||||
- How to review and revise technical content
|
||||
- How to prepare chapters for publisher submission
|
||||
|
||||
Let's begin!
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Plan Your Book
|
||||
|
||||
### Goal
|
||||
Create a high-level book structure with learning objectives and chapter progression.
|
||||
|
||||
### Activate the Instructional Designer
|
||||
|
||||
**In Web UI (Gemini/ChatGPT/Claude)**:
|
||||
1. Navigate to `dist/agents/`
|
||||
2. Upload `instructional-designer.txt` to your chat interface
|
||||
3. The agent will activate and greet you
|
||||
|
||||
**In IDE (Cursor/VS Code/Claude Code)**:
|
||||
```
|
||||
/bmad-tw:instructional-designer
|
||||
```
|
||||
|
||||
The Instructional Designer will greet you and present available commands.
|
||||
|
||||
### Create Book Outline
|
||||
|
||||
**Command**:
|
||||
```
|
||||
*create-book-outline
|
||||
```
|
||||
|
||||
The agent will execute the `design-book-outline` task using the `book-outline-tmpl` template.
|
||||
|
||||
**You'll be asked**:
|
||||
- Book title
|
||||
- Target audience
|
||||
- Prerequisites
|
||||
- Learning outcomes
|
||||
- Chapter topics
|
||||
|
||||
**Example Inputs**:
|
||||
|
||||
> **Book Title**: Python Data Structures Handbook
|
||||
>
|
||||
> **Target Audience**: Beginner to intermediate Python developers who understand basic Python syntax
|
||||
>
|
||||
> **Prerequisites**:
|
||||
> - Basic Python syntax (variables, functions, loops)
|
||||
> - Understanding of types (int, str, bool)
|
||||
> - Python 3.10+ installed
|
||||
>
|
||||
> **Learning Outcomes**:
|
||||
> - Master Python's core data structures (lists, tuples, sets, dicts)
|
||||
> - Choose appropriate data structures for different scenarios
|
||||
> - Implement efficient data manipulation algorithms
|
||||
> - Understand time/space complexity trade-offs
|
||||
>
|
||||
> **Chapters** (10 chapters):
|
||||
> 1. Introduction to Python Data Structures
|
||||
> 2. Lists and List Operations
|
||||
> 3. Tuples and Immutability
|
||||
> 4. Dictionaries and Hash Tables
|
||||
> 5. Sets and Set Operations
|
||||
> 6. Advanced List Techniques
|
||||
> 7. Advanced Dictionary Techniques
|
||||
> 8. Data Structure Performance
|
||||
> 9. Choosing the Right Data Structure
|
||||
> 10. Real-World Applications
|
||||
|
||||
**Output**: `book-outline.md`
|
||||
|
||||
The agent generates a complete book outline with:
|
||||
- Chapter descriptions
|
||||
- Learning objectives per chapter
|
||||
- Prerequisite mapping
|
||||
- Estimated page counts
|
||||
- Difficulty progression
|
||||
|
||||
**Sample Output Section**:
|
||||
```markdown
|
||||
## Chapter 1: Introduction to Python Data Structures
|
||||
|
||||
**Learning Objectives**:
|
||||
- Understand what data structures are and why they matter
|
||||
- Recognize different data structure categories
|
||||
- Implement basic list and tuple operations
|
||||
- Choose between lists and tuples appropriately
|
||||
|
||||
**Prerequisites**: Basic Python syntax, variables, functions
|
||||
|
||||
**Estimated Length**: 18-22 pages
|
||||
|
||||
**Topics**:
|
||||
- Data structures overview
|
||||
- Introduction to sequences (lists, tuples)
|
||||
- List creation and basic operations
|
||||
- Tuple creation and immutability
|
||||
- Lists vs tuples decision criteria
|
||||
```
|
||||
|
||||
### Validate Learning Progression
|
||||
|
||||
**Command**:
|
||||
```
|
||||
*execute-checklist learning-objectives-checklist
|
||||
```
|
||||
|
||||
The agent reviews your book outline against pedagogical best practices:
|
||||
- ✅ Learning objectives are measurable
|
||||
- ✅ Progression follows Bloom's taxonomy
|
||||
- ✅ Prerequisites are clearly stated
|
||||
- ✅ Difficulty curve is appropriate
|
||||
|
||||
**Result**: Validated book outline ready for chapter development.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Plan Your First Chapter
|
||||
|
||||
### Goal
|
||||
Break Chapter 1 into manageable sections with detailed structure.
|
||||
|
||||
### Create Chapter Outline
|
||||
|
||||
**Still with Instructional Designer, command**:
|
||||
```
|
||||
*create-chapter-outline
|
||||
```
|
||||
|
||||
**You'll specify**:
|
||||
- Chapter number (1)
|
||||
- Chapter title
|
||||
- Section breakdown
|
||||
- Code examples needed
|
||||
|
||||
**Example Section Breakdown** (6 sections):
|
||||
|
||||
**Section 1.1: Why Data Structures Matter** (3 pages)
|
||||
- Real-world analogy (organizing a library)
|
||||
- Performance implications
|
||||
- Common pitfalls of wrong choices
|
||||
|
||||
**Section 1.2: Introduction to Lists** (4 pages)
|
||||
- List creation syntax
|
||||
- Basic list operations (append, insert, remove)
|
||||
- List indexing and slicing
|
||||
- Hands-on example: Building a task list
|
||||
|
||||
**Section 1.3: List Methods and Iteration** (3 pages)
|
||||
- Common list methods (sort, reverse, count)
|
||||
- Iterating with for loops
|
||||
- List comprehensions preview
|
||||
- Hands-on example: Processing student grades
|
||||
|
||||
**Section 1.4: Introduction to Tuples** (3 pages)
|
||||
- Tuple creation and syntax
|
||||
- Immutability explained
|
||||
- Tuple unpacking
|
||||
- Hands-on example: Coordinate systems
|
||||
|
||||
**Section 1.5: Lists vs Tuples Decision Guide** (3 pages)
|
||||
- When to use lists (mutable collections)
|
||||
- When to use tuples (immutable records)
|
||||
- Performance considerations
|
||||
- Best practices
|
||||
|
||||
**Section 1.6: Practice Exercises** (3 pages)
|
||||
- 5 progressive exercises
|
||||
- Solutions with explanations
|
||||
|
||||
**Output**: `chapter-01-outline.md`
|
||||
|
||||
### Switch to Tutorial Architect
|
||||
|
||||
Now activate the Tutorial Architect for hands-on section writing:
|
||||
|
||||
**In IDE**:
|
||||
```
|
||||
/bmad-tw:tutorial-architect
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Write Your First Section
|
||||
|
||||
### Goal
|
||||
Write one complete section (Section 1.2: Introduction to Lists) with code examples and tutorial content.
|
||||
|
||||
### Activate Code Curator
|
||||
|
||||
First, we need working code examples. Activate Code Curator:
|
||||
|
||||
**In IDE**:
|
||||
```
|
||||
/bmad-tw:code-curator
|
||||
```
|
||||
|
||||
### Create Code Examples
|
||||
|
||||
**Command**:
|
||||
```
|
||||
*create-code-example
|
||||
```
|
||||
|
||||
**Specify**:
|
||||
- Section: 1.2 - Introduction to Lists
|
||||
- Example title: "Building a Task List Application"
|
||||
- Concepts to demonstrate: List creation, append, remove, indexing
|
||||
|
||||
**Code Curator Creates**:
|
||||
|
||||
`examples/chapter-01/task_list.py`:
|
||||
```python
|
||||
# Task List Application - Introduction to Lists
|
||||
|
||||
def main():
|
||||
"""Demonstrate basic list operations through a task list app."""
|
||||
|
||||
# Create an empty list
|
||||
tasks = []
|
||||
print(f"Starting tasks: {tasks}")
|
||||
|
||||
# Add tasks using append
|
||||
tasks.append("Write chapter outline")
|
||||
tasks.append("Create code examples")
|
||||
tasks.append("Review draft")
|
||||
print(f"After adding tasks: {tasks}")
|
||||
|
||||
# Access tasks by index
|
||||
first_task = tasks[0]
|
||||
print(f"First task: {first_task}")
|
||||
|
||||
# Add task at specific position
|
||||
tasks.insert(1, "Write section 1")
|
||||
print(f"After inserting: {tasks}")
|
||||
|
||||
# Remove completed task
|
||||
tasks.remove("Write chapter outline")
|
||||
print(f"After completing first task: {tasks}")
|
||||
|
||||
# Check remaining tasks
|
||||
print(f"Total remaining tasks: {len(tasks)}")
|
||||
|
||||
# Iterate through tasks
|
||||
print("\nRemaining tasks:")
|
||||
for i, task in enumerate(tasks, 1):
|
||||
print(f"{i}. {task}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
`examples/chapter-01/test_task_list.py`:
|
||||
```python
|
||||
import pytest
|
||||
from task_list import main
|
||||
|
||||
def test_list_creation():
|
||||
"""Test that lists can be created and modified."""
|
||||
tasks = []
|
||||
assert tasks == []
|
||||
|
||||
tasks.append("test task")
|
||||
assert len(tasks) == 1
|
||||
assert tasks[0] == "test task"
|
||||
|
||||
def test_list_operations():
|
||||
"""Test insert and remove operations."""
|
||||
tasks = ["first", "second"]
|
||||
tasks.insert(1, "middle")
|
||||
assert tasks == ["first", "middle", "second"]
|
||||
|
||||
tasks.remove("middle")
|
||||
assert tasks == ["first", "second"]
|
||||
```
|
||||
|
||||
**Command**:
|
||||
```
|
||||
*test-code-examples
|
||||
```
|
||||
|
||||
Code Curator runs tests:
|
||||
```
|
||||
pytest examples/chapter-01/test_task_list.py -v
|
||||
================================ test session starts ================================
|
||||
examples/chapter-01/test_task_list.py::test_list_creation PASSED [ 50%]
|
||||
examples/chapter-01/test_task_list.py::test_list_operations PASSED [100%]
|
||||
================================ 2 passed in 0.03s ==================================
|
||||
✅ All tests passed
|
||||
```
|
||||
|
||||
### Write Section Content
|
||||
|
||||
**Reactivate Tutorial Architect**, command:
|
||||
```
|
||||
*create-tutorial
|
||||
```
|
||||
|
||||
**Specify**:
|
||||
- Section: 1.2 - Introduction to Lists
|
||||
- Use code example: `task_list.py`
|
||||
- Include: explanation, tutorial, troubleshooting
|
||||
|
||||
**Tutorial Architect Writes**:
|
||||
|
||||
`sections/section-1.2-introduction-to-lists.md`:
|
||||
|
||||
```markdown
|
||||
# Section 1.2: Introduction to Lists
|
||||
|
||||
## What You'll Learn
|
||||
|
||||
By the end of this section, you'll be able to:
|
||||
- Create lists in Python
|
||||
- Add items to lists using `append()` and `insert()`
|
||||
- Remove items from lists
|
||||
- Access list items by index
|
||||
- Iterate through lists
|
||||
|
||||
**Prerequisites**: Basic Python syntax, understanding of variables
|
||||
|
||||
**Estimated Time**: 20-30 minutes
|
||||
|
||||
---
|
||||
|
||||
## What are Lists?
|
||||
|
||||
Lists are Python's most versatile data structure. Think of a list as a container that holds multiple items in a specific order, like a to-do list or a shopping list.
|
||||
|
||||
**Key characteristics**:
|
||||
- **Ordered** - Items maintain their position
|
||||
- **Mutable** - You can add, remove, or change items
|
||||
- **Allow duplicates** - The same item can appear multiple times
|
||||
- **Dynamic size** - Lists grow and shrink automatically
|
||||
|
||||
---
|
||||
|
||||
## Creating Lists
|
||||
|
||||
Lists are created using square brackets `[]`:
|
||||
|
||||
```python
|
||||
# Empty list
|
||||
tasks = []
|
||||
|
||||
# List with initial items
|
||||
numbers = [1, 2, 3, 4, 5]
|
||||
names = ["Alice", "Bob", "Charlie"]
|
||||
mixed = [1, "hello", 3.14, True] # Lists can hold different types
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hands-On Tutorial: Building a Task List
|
||||
|
||||
Let's build a simple task list application to learn list operations.
|
||||
|
||||
### Step 1: Create an Empty List
|
||||
|
||||
```python
|
||||
tasks = []
|
||||
print(f"Starting tasks: {tasks}")
|
||||
# Output: Starting tasks: []
|
||||
```
|
||||
|
||||
### Step 2: Add Tasks with append()
|
||||
|
||||
The `append()` method adds an item to the end of the list:
|
||||
|
||||
```python
|
||||
tasks.append("Write chapter outline")
|
||||
tasks.append("Create code examples")
|
||||
tasks.append("Review draft")
|
||||
print(f"After adding tasks: {tasks}")
|
||||
# Output: After adding tasks: ['Write chapter outline', 'Create code examples', 'Review draft']
|
||||
```
|
||||
|
||||
### Step 3: Access Items by Index
|
||||
|
||||
Lists use zero-based indexing. The first item is at index 0:
|
||||
|
||||
```python
|
||||
first_task = tasks[0]
|
||||
print(f"First task: {first_task}")
|
||||
# Output: First task: Write chapter outline
|
||||
```
|
||||
|
||||
### Step 4: Insert Tasks at Specific Position
|
||||
|
||||
Use `insert(position, item)` to add an item at a specific index:
|
||||
|
||||
```python
|
||||
tasks.insert(1, "Write section 1")
|
||||
print(f"After inserting: {tasks}")
|
||||
# Output: After inserting: ['Write chapter outline', 'Write section 1', 'Create code examples', 'Review draft']
|
||||
```
|
||||
|
||||
### Step 5: Remove Completed Tasks
|
||||
|
||||
Use `remove(item)` to delete an item by value:
|
||||
|
||||
```python
|
||||
tasks.remove("Write chapter outline")
|
||||
print(f"After completing first task: {tasks}")
|
||||
# Output: After completing first task: ['Write section 1', 'Create code examples', 'Review draft']
|
||||
```
|
||||
|
||||
### Step 6: Iterate Through Tasks
|
||||
|
||||
Loop through list items with a for loop:
|
||||
|
||||
```python
|
||||
print("\nRemaining tasks:")
|
||||
for i, task in enumerate(tasks, 1):
|
||||
print(f"{i}. {task}")
|
||||
|
||||
# Output:
|
||||
# Remaining tasks:
|
||||
# 1. Write section 1
|
||||
# 2. Create code examples
|
||||
# 3. Review draft
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Expected Output
|
||||
|
||||
When you run the complete example:
|
||||
|
||||
```
|
||||
python examples/chapter-01/task_list.py
|
||||
```
|
||||
|
||||
You should see:
|
||||
|
||||
```
|
||||
Starting tasks: []
|
||||
After adding tasks: ['Write chapter outline', 'Create code examples', 'Review draft']
|
||||
First task: Write chapter outline
|
||||
After inserting: ['Write chapter outline', 'Write section 1', 'Create code examples', 'Review draft']
|
||||
After completing first task: ['Write section 1', 'Create code examples', 'Review draft']
|
||||
Total remaining tasks: 3
|
||||
|
||||
Remaining tasks:
|
||||
1. Write section 1
|
||||
2. Create code examples
|
||||
3. Review draft
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues and Troubleshooting
|
||||
|
||||
### Issue: IndexError: list index out of range
|
||||
|
||||
**Cause**: Trying to access an index that doesn't exist
|
||||
|
||||
```python
|
||||
tasks = ["task 1", "task 2"]
|
||||
print(tasks[5]) # Error! Only indices 0 and 1 exist
|
||||
```
|
||||
|
||||
**Solution**: Check list length before accessing:
|
||||
```python
|
||||
if len(tasks) > 5:
|
||||
print(tasks[5])
|
||||
else:
|
||||
print("Index out of range")
|
||||
```
|
||||
|
||||
### Issue: ValueError: list.remove(x): x not in list
|
||||
|
||||
**Cause**: Trying to remove an item that doesn't exist
|
||||
|
||||
**Solution**: Check if item exists first:
|
||||
```python
|
||||
if "task" in tasks:
|
||||
tasks.remove("task")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
- Lists are created with square brackets: `[]`
|
||||
- `append(item)` adds to the end
|
||||
- `insert(index, item)` adds at a specific position
|
||||
- `remove(item)` deletes the first occurrence
|
||||
- Lists use zero-based indexing: `tasks[0]` is the first item
|
||||
- `len(list)` returns the number of items
|
||||
|
||||
---
|
||||
|
||||
## Practice Exercise
|
||||
|
||||
Create a shopping list application that:
|
||||
1. Creates an empty list
|
||||
2. Adds 5 items
|
||||
3. Removes 1 item
|
||||
4. Prints the final list
|
||||
|
||||
Try it yourself before checking the solution!
|
||||
|
||||
**Solution**:
|
||||
```python
|
||||
shopping = []
|
||||
shopping.append("apples")
|
||||
shopping.append("bread")
|
||||
shopping.append("milk")
|
||||
shopping.append("eggs")
|
||||
shopping.append("cheese")
|
||||
shopping.remove("milk")
|
||||
print(f"Shopping list: {shopping}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Next**: Section 1.3 - List Methods and Iteration
|
||||
```
|
||||
|
||||
**Output**: Complete section (~3 pages) with tutorial, code, and exercises.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Review Your Section
|
||||
|
||||
### Goal
|
||||
Ensure technical accuracy and quality before moving forward.
|
||||
|
||||
### Activate Technical Reviewer
|
||||
|
||||
**In IDE**:
|
||||
```
|
||||
/bmad-tw:technical-reviewer
|
||||
```
|
||||
|
||||
### Run Technical Review
|
||||
|
||||
**Command**:
|
||||
```
|
||||
*review-section sections/section-1.2-introduction-to-lists.md
|
||||
```
|
||||
|
||||
**Technical Reviewer checks**:
|
||||
- ✅ Code examples are correct
|
||||
- ✅ Security best practices followed
|
||||
- ✅ Performance considerations noted
|
||||
- ✅ Error handling appropriate
|
||||
- ✅ Python version compatibility (3.10+)
|
||||
|
||||
**Review Output**: `reviews/section-1.2-review.md`
|
||||
|
||||
```markdown
|
||||
# Technical Review: Section 1.2
|
||||
|
||||
## Overall Assessment: APPROVED ✅
|
||||
|
||||
## Code Accuracy: ✅ PASS
|
||||
- All code examples tested and working
|
||||
- Syntax is correct for Python 3.10+
|
||||
- Examples demonstrate concepts clearly
|
||||
|
||||
## Security: ✅ PASS
|
||||
- No security vulnerabilities
|
||||
- Examples use safe practices
|
||||
|
||||
## Best Practices: ✅ PASS
|
||||
- Follows PEP 8 style guidelines
|
||||
- Proper error handling demonstrated
|
||||
- Good variable naming
|
||||
|
||||
## Minor Suggestions:
|
||||
1. Consider adding example with list slicing
|
||||
2. Could mention list() constructor as alternative
|
||||
|
||||
## Recommendation: READY FOR PUBLICATION
|
||||
```
|
||||
|
||||
### Apply Review Feedback (Optional)
|
||||
|
||||
**Tutorial Architect adds slicing example**:
|
||||
|
||||
```python
|
||||
# List slicing
|
||||
first_two = tasks[:2]
|
||||
print(f"First two tasks: {first_two}")
|
||||
```
|
||||
|
||||
**Section updated and marked complete** ✅
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Complete Remaining Sections
|
||||
|
||||
### Repeat Process for All Sections
|
||||
|
||||
You've now completed Section 1.2. Repeat Steps 3-4 for remaining sections:
|
||||
|
||||
- **Section 1.1**: Why Data Structures Matter ⏳
|
||||
- **Section 1.2**: Introduction to Lists ✅
|
||||
- **Section 1.3**: List Methods and Iteration ⏳
|
||||
- **Section 1.4**: Introduction to Tuples ⏳
|
||||
- **Section 1.5**: Lists vs Tuples Decision Guide ⏳
|
||||
- **Section 1.6**: Practice Exercises ⏳
|
||||
|
||||
### Track Progress
|
||||
|
||||
As you complete sections, you'll have:
|
||||
```
|
||||
sections/
|
||||
├── section-1.1-why-data-structures-matter.md ⏳
|
||||
├── section-1.2-introduction-to-lists.md ✅
|
||||
├── section-1.3-list-methods-iteration.md ⏳
|
||||
├── section-1.4-introduction-to-tuples.md ⏳
|
||||
├── section-1.5-lists-vs-tuples.md ⏳
|
||||
└── section-1.6-practice-exercises.md ⏳
|
||||
```
|
||||
|
||||
### Parallel Development (Optional)
|
||||
|
||||
You can work on multiple sections simultaneously by:
|
||||
- Writing Section 1.3 while Section 1.2 is in review
|
||||
- Having Code Curator create all code examples first
|
||||
- Batch reviewing multiple sections
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Assemble Your Chapter
|
||||
|
||||
### Goal
|
||||
Merge all sections into a cohesive chapter with smooth transitions.
|
||||
|
||||
### Activate Technical Editor
|
||||
|
||||
**In IDE**:
|
||||
```
|
||||
/bmad-tw:technical-editor
|
||||
```
|
||||
|
||||
### Run Chapter Assembly Workflow
|
||||
|
||||
**Command**:
|
||||
```
|
||||
*assemble-chapter
|
||||
```
|
||||
|
||||
**Specify**:
|
||||
- Chapter number: 1
|
||||
- Sections to merge: All 6 sections
|
||||
- Output file: `chapters/chapter-01-introduction.md`
|
||||
|
||||
**Technical Editor**:
|
||||
1. Merges all sections in order
|
||||
2. Adds smooth transitions between sections
|
||||
3. Creates chapter introduction
|
||||
4. Writes chapter summary
|
||||
5. Ensures consistent style and tone
|
||||
6. Validates cross-references
|
||||
7. Runs checklists
|
||||
|
||||
**Output**: `chapters/chapter-01-introduction.md` (complete ~20-page chapter)
|
||||
|
||||
### Validate Chapter
|
||||
|
||||
**Command**:
|
||||
```
|
||||
*execute-checklist chapter-completeness-checklist
|
||||
```
|
||||
|
||||
**Checks**:
|
||||
- ✅ All sections present
|
||||
- ✅ Introduction sets expectations
|
||||
- ✅ Summary recaps key points
|
||||
- ✅ Code examples work
|
||||
- ✅ Exercises included
|
||||
- ✅ Cross-references valid
|
||||
- ✅ Consistent formatting
|
||||
|
||||
**Result**: Publisher-ready Chapter 1 ✅
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Prepare for Publishing
|
||||
|
||||
### Goal
|
||||
Package chapter for publisher submission (e.g., PacktPub).
|
||||
|
||||
### Activate Book Publisher
|
||||
|
||||
**In IDE**:
|
||||
```
|
||||
/bmad-tw:book-publisher
|
||||
```
|
||||
|
||||
### Choose Publisher Workflow
|
||||
|
||||
**Command** (for PacktPub):
|
||||
```
|
||||
*run-workflow packtpub-submission
|
||||
```
|
||||
|
||||
**Book Publisher**:
|
||||
1. Formats chapter to PacktPub standards
|
||||
2. Generates submission checklist
|
||||
3. Packages code examples
|
||||
4. Creates chapter metadata
|
||||
5. Prepares submission folder
|
||||
|
||||
**Output**:
|
||||
```
|
||||
submission/
|
||||
├── chapter-01-introduction.docx
|
||||
├── chapter-01-metadata.yaml
|
||||
├── code-examples/
|
||||
│ ├── task_list.py
|
||||
│ ├── test_task_list.py
|
||||
│ └── README.md
|
||||
└── submission-checklist.md
|
||||
```
|
||||
|
||||
### Final Validation
|
||||
|
||||
**Command**:
|
||||
```
|
||||
*execute-checklist packtpub-submission-checklist
|
||||
```
|
||||
|
||||
**Validates**:
|
||||
- ✅ Chapter formatted correctly
|
||||
- ✅ Code examples packaged
|
||||
- ✅ Tests pass
|
||||
- ✅ Metadata complete
|
||||
- ✅ Word count within range (18-22 pages)
|
||||
- ✅ All images/diagrams included
|
||||
- ✅ Submission guidelines met
|
||||
|
||||
**Result**: Ready for publisher submission! 🎉
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
Congratulations! You've completed your first technical book chapter using BMad.
|
||||
|
||||
### Continue Your Book
|
||||
|
||||
**Option 1: Write Chapter 2**
|
||||
```
|
||||
*create-chapter-outline
|
||||
# Chapter 2: Lists and List Operations
|
||||
```
|
||||
|
||||
**Option 2: Add More Sections to Chapter 1**
|
||||
```
|
||||
*create-section
|
||||
# Add advanced list topics
|
||||
```
|
||||
|
||||
### Explore More Features
|
||||
|
||||
**Try Different Workflows**:
|
||||
- `tutorial-creation-workflow` - Create hands-on tutorials
|
||||
- `code-example-workflow` - Focus on code-heavy chapters
|
||||
- `technical-review-workflow` - Deep technical review
|
||||
|
||||
**Use Specialist Agents**:
|
||||
- `api-documenter` - Create API reference chapters
|
||||
- `screenshot-specialist` - Add visual documentation
|
||||
- `exercise-creator` - Design comprehensive exercise sets
|
||||
|
||||
### Learn Advanced Topics
|
||||
|
||||
**Read More Documentation**:
|
||||
- [Process Flows](process-flows.md) - Visualize all workflows
|
||||
- [Agent Reference](agent-reference.md) - Master all 13 agents
|
||||
- [Workflow Guide](workflow-guide.md) - Choose optimal workflows
|
||||
- [Template Gallery](template-gallery.md) - Customize templates
|
||||
|
||||
### Join the Community
|
||||
|
||||
- **Discord**: [Join BMad Community](https://discord.gg/gk8jAdXWmj)
|
||||
- **GitHub**: [Star the repo](https://github.com/bmadcode/bmad-method)
|
||||
- **Share**: Show us what you're building!
|
||||
|
||||
---
|
||||
|
||||
## Tutorial Summary
|
||||
|
||||
You learned how to:
|
||||
|
||||
✅ Plan a complete book with learning objectives
|
||||
✅ Break chapters into manageable sections
|
||||
✅ Write tutorial content with hands-on examples
|
||||
✅ Create and test working code examples
|
||||
✅ Review content for technical accuracy
|
||||
✅ Assemble sections into complete chapters
|
||||
✅ Prepare chapters for publisher submission
|
||||
|
||||
**Time Investment**: 2-3 hours
|
||||
**Output**: 1 publisher-ready chapter (20 pages)
|
||||
**Skills Gained**: Complete technical book authoring workflow
|
||||
|
||||
---
|
||||
|
||||
## Questions or Issues?
|
||||
|
||||
- 📖 [User Guide](user-guide.md) - Conceptual overview
|
||||
- 📋 [Quick Reference](quick-reference.md) - Command cheat sheet
|
||||
- ❓ [FAQ](faq.md) - Common questions
|
||||
- 🐛 [Troubleshooting](troubleshooting.md) - Common issues
|
||||
- 💬 [Discord](https://discord.gg/gk8jAdXWmj) - Get help
|
||||
|
||||
**Ready to master technical book writing? Keep going!**
|
||||
|
||||
---
|
||||
|
||||
*Getting Started Tutorial - Technical Writing Expansion Pack v1.1.0*
|
||||
|
|
@ -0,0 +1,355 @@
|
|||
# Integration Guide - Technical Writing Expansion Pack
|
||||
|
||||
How to integrate the Technical Writing Expansion Pack with BMad core, other expansion packs, and development tools.
|
||||
|
||||
## BMad Core Integration
|
||||
|
||||
### When to Use Technical Writing vs Core Agents
|
||||
|
||||
**Use Technical Writing Expansion**:
|
||||
- Writing technical books with code examples
|
||||
- Creating tutorial-based content
|
||||
- Need publisher-specific formatting
|
||||
- Require learning objectives and pedagogical structure
|
||||
|
||||
**Use BMad Core**:
|
||||
- Software project planning (PRD, architecture)
|
||||
- Application development (coding, testing, deployment)
|
||||
- Non-book technical documentation
|
||||
|
||||
**Use Both Together**:
|
||||
- Writing a book about your software product
|
||||
- Creating comprehensive documentation for your project
|
||||
|
||||
### Workflow Combination Example
|
||||
|
||||
**Scenario**: Writing a technical book about your software product
|
||||
|
||||
```
|
||||
1. BMad Core: PM creates PRD for software
|
||||
2. BMad Core: Architect designs system
|
||||
3. BMad Core: Dev builds product
|
||||
4. Technical Writing: Instructional Designer creates book outline
|
||||
5. Technical Writing: Tutorial Architect writes chapters about the product
|
||||
6. Technical Writing: Code Curator uses actual product code as examples
|
||||
7. Technical Writing: Book Publisher prepares manuscript
|
||||
```
|
||||
|
||||
### Agent Coordination
|
||||
|
||||
**PM (Core) → Instructional Designer (TW)**:
|
||||
- PM's product requirements inform book learning objectives
|
||||
- User stories become tutorial sections
|
||||
|
||||
**Architect (Core) → Tutorial Architect (TW)**:
|
||||
- Architecture diagrams become book visuals
|
||||
- System design informs chapter structure
|
||||
|
||||
**Dev (Core) → Code Curator (TW)**:
|
||||
- Product code becomes book examples
|
||||
- Tests become tutorial verification
|
||||
|
||||
---
|
||||
|
||||
## Multi-Expansion Usage
|
||||
|
||||
### Technical Writing + Creative Writing
|
||||
|
||||
**Use Case**: Fiction with technical appendices, or technical books with narrative elements
|
||||
|
||||
**Example**:
|
||||
- Creative Writing agents for engaging story-based introductions
|
||||
- Technical Writing agents for code examples and tutorials
|
||||
- Both expansions for mixed-format content
|
||||
|
||||
**Workflow**:
|
||||
```
|
||||
1. Creative Writing: Narrative Designer creates engaging scenarios
|
||||
2. Technical Writing: Tutorial Architect builds tutorials using scenarios
|
||||
3. Creative Writing: Beta Reader reviews narrative flow
|
||||
4. Technical Writing: Technical Reviewer validates code
|
||||
```
|
||||
|
||||
### Technical Writing + Infrastructure
|
||||
|
||||
**Use Case**: DevOps and cloud infrastructure books
|
||||
|
||||
**Example**:
|
||||
- Infrastructure agents for cloud architecture examples
|
||||
- Technical Writing agents for tutorial structure and publishing
|
||||
|
||||
**Workflow**:
|
||||
```
|
||||
1. Infrastructure: Platform Engineer creates deployment examples
|
||||
2. Technical Writing: Code Curator integrates infrastructure code
|
||||
3. Technical Writing: Tutorial Architect explains deployment processes
|
||||
4. Infrastructure: DevOps specialist validates configurations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git Integration
|
||||
|
||||
### Managing Book Manuscripts in Git
|
||||
|
||||
**Recommended Structure**:
|
||||
```
|
||||
my-technical-book/
|
||||
├── .git/
|
||||
├── .bmad-core/
|
||||
│ └── core-config.yaml
|
||||
├── docs/
|
||||
│ ├── planning/
|
||||
│ │ ├── book-outline.md
|
||||
│ │ └── chapter-outlines/
|
||||
│ ├── sections/
|
||||
│ │ ├── chapter-01/
|
||||
│ │ │ ├── section-1.1.md
|
||||
│ │ │ └── section-1.2.md
|
||||
│ │ └── chapter-02/
|
||||
│ ├── chapters/
|
||||
│ │ ├── chapter-01.md
|
||||
│ │ └── chapter-02.md
|
||||
│ └── reviews/
|
||||
├── code-examples/
|
||||
│ ├── chapter-01/
|
||||
│ └── chapter-02/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Branch Strategies
|
||||
|
||||
**Feature Branch per Chapter**:
|
||||
```bash
|
||||
git checkout -b chapter-03-dictionaries
|
||||
# Develop chapter 3
|
||||
git commit -m "feat: complete section 3.1"
|
||||
git commit -m "feat: complete section 3.2"
|
||||
git checkout main
|
||||
git merge chapter-03-dictionaries
|
||||
```
|
||||
|
||||
**Section-Based Commits**:
|
||||
```bash
|
||||
# Commit after each section completes
|
||||
git add docs/sections/chapter-01/section-1.1.md
|
||||
git commit -m "feat(ch01): complete section 1.1 - Lists Introduction"
|
||||
|
||||
git add code-examples/chapter-01/section-1.1/
|
||||
git commit -m "feat(ch01): add code examples for section 1.1"
|
||||
```
|
||||
|
||||
### Collaboration Workflows
|
||||
|
||||
**Multiple Authors**:
|
||||
```bash
|
||||
# Author 1: Chapters 1-5
|
||||
git checkout -b author1/chapters-1-5
|
||||
|
||||
# Author 2: Chapters 6-10
|
||||
git checkout -b author2/chapters-6-10
|
||||
|
||||
# Merge completed chapters
|
||||
git checkout main
|
||||
git merge author1/chapters-1-5
|
||||
git merge author2/chapters-6-10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### Automated Testing of Code Examples
|
||||
|
||||
**GitHub Actions Example**:
|
||||
```yaml
|
||||
name: Test Code Examples
|
||||
|
||||
on:
|
||||
push:
|
||||
paths:
|
||||
- 'code-examples/**'
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v2
|
||||
with:
|
||||
python-version: '3.10'
|
||||
- name: Test Chapter 1 Examples
|
||||
run: |
|
||||
cd code-examples/chapter-01
|
||||
pytest -v
|
||||
- name: Test Chapter 2 Examples
|
||||
run: |
|
||||
cd code-examples/chapter-02
|
||||
pytest -v
|
||||
```
|
||||
|
||||
### Continuous Deployment to Leanpub
|
||||
|
||||
**Auto-publish on merge**:
|
||||
```yaml
|
||||
name: Publish to Leanpub
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: Trigger Leanpub Build
|
||||
run: |
|
||||
curl -d "api_key=${{ secrets.LEANPUB_API_KEY }}" \
|
||||
https://leanpub.com/your-book/preview.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Integration
|
||||
|
||||
### Markdown Editors
|
||||
|
||||
**VS Code**:
|
||||
- Markdown All in One extension
|
||||
- Markdown Preview Enhanced
|
||||
- Code Spell Checker
|
||||
|
||||
**Typora**:
|
||||
- WYSIWYG markdown editing
|
||||
- Export to multiple formats
|
||||
- Math equation support
|
||||
|
||||
### Diagram Tools
|
||||
|
||||
**Mermaid**:
|
||||
```markdown
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Start] --> B[Process]
|
||||
B --> C[End]
|
||||
```
|
||||
```
|
||||
|
||||
**PlantUML**:
|
||||
- UML diagrams
|
||||
- Sequence diagrams
|
||||
- Class diagrams
|
||||
|
||||
### Screenshot Tools
|
||||
|
||||
**Snagit**:
|
||||
- Screen capture
|
||||
- Annotations
|
||||
- Video capture
|
||||
|
||||
**macOS Built-in**:
|
||||
- Cmd+Shift+4 for selection
|
||||
- Cmd+Shift+5 for options
|
||||
|
||||
### Code Repository Hosting
|
||||
|
||||
**GitHub**:
|
||||
- Host book code examples
|
||||
- CI/CD integration
|
||||
- Issue tracking
|
||||
|
||||
**GitLab**:
|
||||
- Built-in CI/CD
|
||||
- Container registry
|
||||
- Pages for previews
|
||||
|
||||
---
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Example 1: Technical Book About Your Product
|
||||
|
||||
**Tools**:
|
||||
- BMad Core (for product development)
|
||||
- Technical Writing Pack (for book authoring)
|
||||
- GitHub (for code hosting)
|
||||
- GitHub Actions (for CI/CD)
|
||||
|
||||
**Workflow**:
|
||||
1. Develop product with BMad Core agents
|
||||
2. Plan book with Instructional Designer
|
||||
3. Write chapters using real product code
|
||||
4. Automatically test code examples in CI
|
||||
5. Publish to self-publishing platform
|
||||
|
||||
### Example 2: Multi-Author Collaboration
|
||||
|
||||
**Tools**:
|
||||
- Technical Writing Pack (for authoring)
|
||||
- Git (for version control)
|
||||
- Discord (for communication)
|
||||
- Leanpub (for publishing)
|
||||
|
||||
**Workflow**:
|
||||
1. Authors claim chapters
|
||||
2. Each author works in feature branch
|
||||
3. Sections committed as completed
|
||||
4. Technical Reviewer reviews PRs
|
||||
5. Merged chapters auto-deploy to Leanpub preview
|
||||
|
||||
### Example 3: Continuous Publishing
|
||||
|
||||
**Tools**:
|
||||
- Technical Writing Pack (for authoring)
|
||||
- GitHub Actions (for automation)
|
||||
- Leanpub (for publishing)
|
||||
- Manning MEAP (for early access)
|
||||
|
||||
**Workflow**:
|
||||
1. Complete chapter triggers CI tests
|
||||
2. All tests pass → auto-format for publisher
|
||||
3. Auto-submit to Leanpub preview
|
||||
4. Manual review → submit to Manning MEAP
|
||||
5. Continuous updates published automatically
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Version Control
|
||||
- Commit sections individually for granular history
|
||||
- Use conventional commits (`feat:`, `fix:`, `docs:`)
|
||||
- Tag releases (`v1.0`, `v1.1`)
|
||||
|
||||
### CI/CD
|
||||
- Test all code examples automatically
|
||||
- Validate markdown formatting
|
||||
- Check spelling and grammar
|
||||
- Auto-generate previews
|
||||
|
||||
### Collaboration
|
||||
- Clear chapter ownership
|
||||
- Regular sync meetings
|
||||
- Shared style guide
|
||||
- Code review for technical content
|
||||
|
||||
### Publishing
|
||||
- Automate format conversion
|
||||
- Test on multiple platforms
|
||||
- Version control submission packages
|
||||
- Maintain changelog
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
- 📖 [User Guide](user-guide.md) - System overview
|
||||
- 🔧 [Troubleshooting](troubleshooting.md) - Common issues
|
||||
- 💬 [Discord](https://discord.gg/gk8jAdXWmj) - Community support
|
||||
|
||||
---
|
||||
|
||||
*Integration Guide - Technical Writing Expansion Pack v1.1.0*
|
||||
|
|
@ -0,0 +1,919 @@
|
|||
# Process Flow Diagrams - Technical Writing Expansion Pack
|
||||
|
||||
Visual representations of all workflows, agent collaboration patterns, and the complete book authoring lifecycle.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [How to Read These Diagrams](#how-to-read-these-diagrams)
|
||||
- [High-Level Overview](#high-level-overview)
|
||||
- [Book Authoring Lifecycle](#book-authoring-lifecycle)
|
||||
- [Agent Collaboration Map](#agent-collaboration-map)
|
||||
- [Planning Workflows](#planning-workflows)
|
||||
- [Book Planning Workflow](#book-planning-workflow)
|
||||
- [Development Workflows](#development-workflows)
|
||||
- [Section-Driven Development Flow](#section-driven-development-flow)
|
||||
- [Section Development Workflow](#section-development-workflow)
|
||||
- [Chapter Assembly Workflow](#chapter-assembly-workflow)
|
||||
- [Tutorial Creation Workflow](#tutorial-creation-workflow)
|
||||
- [Code Example Workflow](#code-example-workflow)
|
||||
- [Review Workflows](#review-workflows)
|
||||
- [Technical Review Workflow](#technical-review-workflow)
|
||||
- [Incorporate Review Feedback Workflow](#incorporate-review-feedback-workflow)
|
||||
- [Publishing Workflows](#publishing-workflows)
|
||||
- [Publishing Decision Tree](#publishing-decision-tree)
|
||||
- [PacktPub Submission Workflow](#packtpub-submission-workflow)
|
||||
- [O'Reilly Submission Workflow](#oreilly-submission-workflow)
|
||||
- [Manning MEAP Workflow](#manning-meap-workflow)
|
||||
- [Self-Publishing Workflow](#self-publishing-workflow)
|
||||
- [Brownfield Workflows](#brownfield-workflows)
|
||||
- [Book Edition Update Workflow](#book-edition-update-workflow)
|
||||
- [Add Chapter to Existing Book Workflow](#add-chapter-to-existing-book-workflow)
|
||||
|
||||
---
|
||||
|
||||
## How to Read These Diagrams
|
||||
|
||||
### Diagram Notation
|
||||
|
||||
**Node Colors**:
|
||||
- 🟡 **Yellow (Planning)** - Initial planning and design activities
|
||||
- 🟠 **Orange (Development)** - Content creation and code development
|
||||
- 🔵 **Blue (Review)** - Quality assurance and validation activities
|
||||
- 🟢 **Green (Complete)** - Finished deliverables and outcomes
|
||||
- ⚪ **White (Decision)** - Decision points requiring evaluation
|
||||
|
||||
**Arrow Types**:
|
||||
- **Solid arrows** → Required sequence (must follow this path)
|
||||
- **Dotted arrows** -.-> Optional steps (can be included if needed)
|
||||
|
||||
**Agent Indicators**:
|
||||
Each process step shows which agent performs the work:
|
||||
- `agent-name: Action Description`
|
||||
|
||||
### Reading Flow
|
||||
|
||||
1. **Start at the top** - Entry point with prerequisites
|
||||
2. **Follow solid arrows** - Required sequence of steps
|
||||
3. **Check decision diamonds** - Branching based on outcomes
|
||||
4. **Note agent handoffs** - Where one agent passes work to another
|
||||
5. **End at green nodes** - Final deliverables
|
||||
|
||||
---
|
||||
|
||||
## High-Level Overview
|
||||
|
||||
### Book Authoring Lifecycle
|
||||
|
||||
Complete journey from book concept to published book.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Book Concept] --> B{Greenfield or Brownfield?}
|
||||
B -->|New Book| C[Planning Phase]
|
||||
B -->|Existing Book| D[Brownfield Analysis]
|
||||
|
||||
C --> E[Book Planning Workflow]
|
||||
E --> F[Book Outline Approved]
|
||||
|
||||
D --> G[Book Edition Update Workflow]
|
||||
G --> F
|
||||
|
||||
F --> H[Development Phase]
|
||||
H --> I{Development Approach?}
|
||||
I -->|Section-Driven| J[Section Planning]
|
||||
I -->|Chapter-at-Once| K[Chapter Development]
|
||||
|
||||
J --> L[Section Development Loop]
|
||||
L --> M{All Sections Done?}
|
||||
M -->|No| L
|
||||
M -->|Yes| N[Chapter Assembly]
|
||||
|
||||
K --> N
|
||||
|
||||
N --> O[Chapter Complete]
|
||||
O --> P{More Chapters?}
|
||||
P -->|Yes| H
|
||||
P -->|No| Q[Review Phase]
|
||||
|
||||
Q --> R[Technical Review Workflow]
|
||||
R --> S[Incorporate Feedback]
|
||||
S --> T[Editing Phase]
|
||||
|
||||
T --> U[Technical Editor Polish]
|
||||
U --> V[Publishing Phase]
|
||||
|
||||
V --> W{Publisher Type?}
|
||||
W -->|PacktPub| X[PacktPub Submission]
|
||||
W -->|O'Reilly| Y[O'Reilly Submission]
|
||||
W -->|Manning| Z[Manning MEAP]
|
||||
W -->|Self-Publish| AA[Self-Publishing Workflow]
|
||||
|
||||
X --> AB[Manuscript Submitted]
|
||||
Y --> AB
|
||||
Z --> AB
|
||||
AA --> AB
|
||||
|
||||
AB --> AC[Book Published!]
|
||||
|
||||
style A fill:#E0E0E0
|
||||
style F fill:#FFD700
|
||||
style O fill:#98FB98
|
||||
style AB fill:#90EE90
|
||||
style AC fill:#32CD32
|
||||
```
|
||||
|
||||
**Caption**: The complete book authoring lifecycle showing greenfield and brownfield paths, development approaches, and publishing options.
|
||||
|
||||
---
|
||||
|
||||
### Agent Collaboration Map
|
||||
|
||||
Shows which agents collaborate with which other agents throughout the workflow.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph Planning_Agents
|
||||
ID[Instructional Designer]
|
||||
TA[Tutorial Architect]
|
||||
BP[Book Publisher]
|
||||
end
|
||||
|
||||
subgraph Development_Agents
|
||||
CC[Code Curator]
|
||||
TA2[Tutorial Architect]
|
||||
EC[Exercise Creator]
|
||||
end
|
||||
|
||||
subgraph Review_Agents
|
||||
TR[Technical Reviewer]
|
||||
TE[Technical Editor]
|
||||
end
|
||||
|
||||
subgraph Specialist_Agents
|
||||
AD[API Documenter]
|
||||
SS[Screenshot Specialist]
|
||||
end
|
||||
|
||||
subgraph Brownfield_Agents
|
||||
BA[Book Analyst]
|
||||
end
|
||||
|
||||
subgraph Optional_Agents
|
||||
LPD[Learning Path Designer]
|
||||
SCM[Sample Code Maintainer]
|
||||
VM[Version Manager]
|
||||
end
|
||||
|
||||
%% Primary collaborations
|
||||
ID --> TA2
|
||||
ID --> BP
|
||||
TA2 --> CC
|
||||
CC --> TR
|
||||
TR --> TA2
|
||||
TA2 --> TE
|
||||
TE --> BP
|
||||
BP --> AD
|
||||
BP --> SS
|
||||
|
||||
%% Specialist integrations
|
||||
CC --> EC
|
||||
TA2 --> AD
|
||||
TA2 --> SS
|
||||
|
||||
%% Brownfield integrations
|
||||
BA --> ID
|
||||
BA --> TA2
|
||||
BA --> CC
|
||||
|
||||
%% Optional agent enhancements
|
||||
LPD -.-> ID
|
||||
SCM -.-> CC
|
||||
VM -.-> CC
|
||||
|
||||
style ID fill:#FFE4B5
|
||||
style TA2 fill:#FFE4B5
|
||||
style CC fill:#F0E68C
|
||||
style TR fill:#ADD8E6
|
||||
style TE fill:#ADD8E6
|
||||
style BP fill:#90EE90
|
||||
```
|
||||
|
||||
**Caption**: Agent collaboration patterns showing primary workflows (solid) and optional integrations (dotted).
|
||||
|
||||
**Key Collaborations**:
|
||||
- **Instructional Designer → Tutorial Architect**: Passes learning objectives and chapter structure
|
||||
- **Tutorial Architect → Code Curator**: Requests code examples for tutorials
|
||||
- **Code Curator → Technical Reviewer**: Submits code for technical accuracy review
|
||||
- **Technical Reviewer → Tutorial Architect**: Returns review feedback for revisions
|
||||
- **Tutorial Architect → Technical Editor**: Passes completed content for polish
|
||||
- **Technical Editor → Book Publisher**: Delivers polished manuscript for publication prep
|
||||
|
||||
---
|
||||
|
||||
## Planning Workflows
|
||||
|
||||
### Book Planning Workflow
|
||||
|
||||
Complete book planning from concept to approved outline.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Start: Book Concept] --> B[book-publisher: Draft Proposal]
|
||||
B --> C[instructional-designer: Design Outline]
|
||||
C --> D[instructional-designer: Validate Learning Path]
|
||||
D --> E{Prerequisites Flow?}
|
||||
E -->|Issues Found| F[instructional-designer: Adjust Outline]
|
||||
F --> D
|
||||
E -->|Valid| G[technical-editor: Editorial Review]
|
||||
G --> H[book-publisher: Publisher Format Check]
|
||||
H --> I{Meets Requirements?}
|
||||
I -->|Needs Changes| J[Adjust for Publisher]
|
||||
J --> G
|
||||
I -->|Approved| K[Final Outline Approved]
|
||||
K --> L[Ready for Chapter Development]
|
||||
|
||||
B -.-> B1[Optional: Market Research]
|
||||
C -.-> C1[Optional: Competitive Analysis]
|
||||
D -.-> D1[Optional: Pedagogical Review]
|
||||
|
||||
style L fill:#90EE90
|
||||
style B fill:#FFE4B5
|
||||
style C fill:#FFE4B5
|
||||
style D fill:#ADD8E6
|
||||
style G fill:#ADD8E6
|
||||
style H fill:#F0E68C
|
||||
```
|
||||
|
||||
**Caption**: Book planning workflow coordinates Book Publisher, Instructional Designer, and Technical Editor to create pedagogically sound, publisher-compliant book outline.
|
||||
|
||||
**Time Estimate**: 20-33 hours
|
||||
**Agents Involved**: Book Publisher, Instructional Designer, Technical Editor
|
||||
|
||||
**Key Steps**:
|
||||
1. **Draft Proposal** - Book Publisher creates comprehensive proposal with market analysis
|
||||
2. **Design Outline** - Instructional Designer creates detailed chapter structure with learning objectives
|
||||
3. **Validate Learning Path** - Instructional Designer checks prerequisite flow and difficulty progression
|
||||
4. **Editorial Review** - Technical Editor ensures clarity and consistency
|
||||
5. **Publisher Check** - Book Publisher verifies format compliance
|
||||
6. **Approval** - Final outline approved for development
|
||||
|
||||
**Quality Gates**:
|
||||
- Proposal includes market analysis, target audience, competitive titles
|
||||
- Outline has clear learning objectives and prerequisites for each chapter
|
||||
- Learning path validated (no knowledge gaps)
|
||||
- Editorial review passed (clarity, consistency)
|
||||
- Publisher requirements met
|
||||
|
||||
---
|
||||
|
||||
## Development Workflows
|
||||
|
||||
### Section-Driven Development Flow
|
||||
|
||||
High-level overview of section-driven approach to chapter development.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Chapter Outline Approved] --> B[Section Planning Workflow]
|
||||
B --> C[Section List Created]
|
||||
C --> D{Select Next Section}
|
||||
D --> E[Section Development Workflow]
|
||||
E --> F[Section DONE]
|
||||
F --> G{More Sections?}
|
||||
G -->|Yes| D
|
||||
G -->|No| H[All Sections Complete]
|
||||
H --> I[Chapter Assembly Workflow]
|
||||
I --> J[Chapter DONE]
|
||||
|
||||
%% Parallel development option
|
||||
D -.-> D1[Section 1]
|
||||
D -.-> D2[Section 2]
|
||||
D -.-> D3[Section 3]
|
||||
D1 -.-> E
|
||||
D2 -.-> E
|
||||
D3 -.-> E
|
||||
|
||||
style A fill:#FFD700
|
||||
style C fill:#FFE4B5
|
||||
style F fill:#98FB98
|
||||
style H fill:#90EE90
|
||||
style J fill:#32CD32
|
||||
```
|
||||
|
||||
**Caption**: Section-driven development breaks chapters into 2-5 page sections that can be developed independently and in parallel.
|
||||
|
||||
**Why Section-Driven?**
|
||||
- **Manageable scope**: Small sections easier to write
|
||||
- **Parallel development**: Multiple sections can progress simultaneously
|
||||
- **Incremental progress**: Each section completion is a milestone
|
||||
- **Quality focus**: Easier to maintain quality in small chunks
|
||||
|
||||
**Typical Chapter**:
|
||||
- 6-8 sections
|
||||
- Each section: 2-5 pages
|
||||
- Total chapter: 18-24 pages
|
||||
|
||||
---
|
||||
|
||||
### Section Development Workflow
|
||||
|
||||
Complete development of one section (the "story" unit of book writing).
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Start: Section Plan Ready] --> B[code-curator: Develop Code Examples]
|
||||
B --> C[code-curator: Test Code Examples]
|
||||
C --> D{All Tests Pass?}
|
||||
D -->|No| E[code-curator: Fix Code]
|
||||
E --> C
|
||||
D -->|Yes| F[tutorial-architect: Write Section]
|
||||
F --> G[technical-reviewer: Quick Review]
|
||||
G --> H{Critical Issues?}
|
||||
H -->|Yes| I[tutorial-architect: Revise Section]
|
||||
I --> J[Update Code if Needed?]
|
||||
J -->|Yes| K[code-curator: Update Code]
|
||||
K --> C
|
||||
J -->|No| G
|
||||
H -->|No| L[tutorial-architect: Verify Acceptance Criteria]
|
||||
L --> M{Criteria Met?}
|
||||
M -->|No| N[Address Missing Items]
|
||||
N --> L
|
||||
M -->|Yes| O[Section DONE]
|
||||
|
||||
B -.-> B1[Use section plan code list]
|
||||
F -.-> F1[Reference section-plan objectives]
|
||||
G -.-> G1[Use technical-accuracy-checklist]
|
||||
L -.-> L1[Check section plan success criteria]
|
||||
|
||||
style O fill:#90EE90
|
||||
style B fill:#FFE4B5
|
||||
style C fill:#FFE4B5
|
||||
style F fill:#FFE4B5
|
||||
style G fill:#ADD8E6
|
||||
style L fill:#F0E68C
|
||||
```
|
||||
|
||||
**Caption**: Section development workflow coordinates Code Curator and Tutorial Architect to create technically accurate, well-tested section content.
|
||||
|
||||
**Time Estimate**: 5.5-10.5 hours per section
|
||||
**Agents Involved**: Code Curator, Tutorial Architect, Technical Reviewer
|
||||
|
||||
**Key Steps**:
|
||||
1. **Develop Code** - Code Curator creates all code examples from section plan
|
||||
2. **Test Code** - Code Curator runs tests, verifies output, handles edge cases
|
||||
3. **Write Section** - Tutorial Architect writes 2-5 page section with code integrated
|
||||
4. **Quick Review** - Technical Reviewer checks accuracy (focused, not full review)
|
||||
5. **Revise** - Tutorial Architect incorporates feedback
|
||||
6. **Verify** - Tutorial Architect confirms all acceptance criteria met
|
||||
7. **Done** - Section marked complete and ready for chapter assembly
|
||||
|
||||
---
|
||||
|
||||
### Chapter Assembly Workflow
|
||||
|
||||
Merge completed sections into cohesive chapter.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[All Sections Complete] --> B[technical-editor: Gather Sections]
|
||||
B --> C[technical-editor: Review Section Order]
|
||||
C --> D{Order Optimal?}
|
||||
D -->|Needs Adjustment| E[Reorder Sections]
|
||||
E --> C
|
||||
D -->|Good| F[technical-editor: Write Chapter Introduction]
|
||||
F --> G[technical-editor: Merge Sections]
|
||||
G --> H[technical-editor: Add Transitions]
|
||||
H --> I[technical-editor: Write Chapter Summary]
|
||||
I --> J[technical-editor: Validate Cross-References]
|
||||
J --> K{Cross-References Valid?}
|
||||
K -->|Issues Found| L[Fix References]
|
||||
L --> J
|
||||
K -->|Valid| M[technical-editor: Check Style Consistency]
|
||||
M --> N[technical-editor: Final Polish]
|
||||
N --> O[Chapter Complete]
|
||||
|
||||
F -.-> F1[Use introduction-tmpl]
|
||||
I -.-> I1[Recap learning objectives]
|
||||
M -.-> M1[chapter-completeness-checklist]
|
||||
|
||||
style A fill:#FFD700
|
||||
style O fill:#90EE90
|
||||
style G fill:#FFE4B5
|
||||
style M fill:#ADD8E6
|
||||
```
|
||||
|
||||
**Caption**: Chapter assembly workflow merges sections with smooth transitions, creating cohesive chapter with introduction and summary.
|
||||
|
||||
**Time Estimate**: 4-6 hours
|
||||
**Agents Involved**: Technical Editor
|
||||
|
||||
**Key Activities**:
|
||||
- Merge all sections in logical order
|
||||
- Add smooth transitions between sections
|
||||
- Write compelling chapter introduction
|
||||
- Create comprehensive chapter summary
|
||||
- Validate all cross-references
|
||||
- Ensure consistent style and tone
|
||||
|
||||
---
|
||||
|
||||
### Tutorial Creation Workflow
|
||||
|
||||
Create comprehensive hands-on tutorials.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Tutorial Topic Defined] --> B[instructional-designer: Define Learning Objectives]
|
||||
B --> C[tutorial-architect: Design Tutorial Structure]
|
||||
C --> D[code-curator: Create Tutorial Code Examples]
|
||||
D --> E[tutorial-architect: Write Step-by-Step Instructions]
|
||||
E --> F[tutorial-architect: Add Expected Outcomes]
|
||||
F --> G[tutorial-architect: Write Troubleshooting Section]
|
||||
G --> H[code-curator: Test Complete Tutorial]
|
||||
H --> I{Tutorial Works End-to-End?}
|
||||
I -->|Issues| J[Fix Tutorial Steps]
|
||||
J --> H
|
||||
I -->|Success| K[exercise-creator: Create Practice Exercises]
|
||||
K --> L[Tutorial Complete]
|
||||
|
||||
B -.-> B1[learning-objectives-tmpl]
|
||||
C -.-> C1[tutorial-section-tmpl]
|
||||
H -.-> H1[tutorial-effectiveness-checklist]
|
||||
|
||||
style A fill:#E0E0E0
|
||||
style L fill:#90EE90
|
||||
style D fill:#FFE4B5
|
||||
style E fill:#FFE4B5
|
||||
style H fill:#ADD8E6
|
||||
```
|
||||
|
||||
**Caption**: Tutorial creation workflow builds complete hands-on learning experiences with working code and practice exercises.
|
||||
|
||||
**Time Estimate**: 8-12 hours
|
||||
**Agents Involved**: Instructional Designer, Tutorial Architect, Code Curator, Exercise Creator
|
||||
|
||||
---
|
||||
|
||||
### Code Example Workflow
|
||||
|
||||
Create, test, and document code examples.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Code Example Needed] --> B[code-curator: Write Code Example]
|
||||
B --> C[code-curator: Write Unit Tests]
|
||||
C --> D[code-curator: Run Tests]
|
||||
D --> E{Tests Pass?}
|
||||
E -->|No| F[Debug and Fix]
|
||||
F --> D
|
||||
E -->|Yes| G[code-curator: Add Inline Comments]
|
||||
G --> H[code-curator: Document Expected Output]
|
||||
H --> I[code-curator: Security Check]
|
||||
I --> J{Security Issues?}
|
||||
J -->|Yes| K[Fix Security Issues]
|
||||
K --> I
|
||||
J -->|No| L[code-curator: Performance Check]
|
||||
L --> M[code-curator: Cross-Platform Test]
|
||||
M --> N{Works on All Platforms?}
|
||||
N -->|Issues| O[Fix Platform Issues]
|
||||
O --> M
|
||||
N -->|Yes| P[Code Example Complete]
|
||||
|
||||
C -.-> C1[code-testing-checklist]
|
||||
I -.-> I1[security-best-practices-checklist]
|
||||
M -.-> M1[cross-platform-checklist]
|
||||
|
||||
style A fill:#E0E0E0
|
||||
style P fill:#90EE90
|
||||
style B fill:#FFE4B5
|
||||
style D fill:#FFE4B5
|
||||
style I fill:#ADD8E6
|
||||
style L fill:#ADD8E6
|
||||
```
|
||||
|
||||
**Caption**: Code example workflow ensures all code is tested, secure, performant, and cross-platform compatible.
|
||||
|
||||
**Time Estimate**: 1-3 hours per example
|
||||
**Agents Involved**: Code Curator
|
||||
|
||||
---
|
||||
|
||||
## Review Workflows
|
||||
|
||||
### Technical Review Workflow
|
||||
|
||||
Comprehensive technical accuracy verification.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Chapter Draft Complete] --> B[technical-reviewer: Read Chapter]
|
||||
B --> C[technical-reviewer: Verify Technical Accuracy]
|
||||
C --> D[technical-reviewer: Test All Code Examples]
|
||||
D --> E{Code Works?}
|
||||
E -->|Issues| F[Document Code Issues]
|
||||
E -->|Pass| G[technical-reviewer: Security Audit]
|
||||
G --> H{Security Issues?}
|
||||
H -->|Yes| I[Document Security Issues]
|
||||
H -->|No| J[technical-reviewer: Check Best Practices]
|
||||
J --> K[technical-reviewer: Performance Review]
|
||||
K --> L[technical-reviewer: Compile Review Report]
|
||||
L --> M{Critical Issues?}
|
||||
M -->|Yes| N[Mark as NEEDS REVISION]
|
||||
M -->|No| O{Major Issues?}
|
||||
O -->|Yes| P[Mark as APPROVED WITH CHANGES]
|
||||
O -->|No| Q[Mark as APPROVED]
|
||||
|
||||
F --> L
|
||||
I --> L
|
||||
|
||||
C -.-> C1[technical-accuracy-checklist]
|
||||
G -.-> G1[security-best-practices-checklist]
|
||||
K -.-> K1[performance-considerations-checklist]
|
||||
|
||||
style A fill:#FFD700
|
||||
style N fill:#FF6B6B
|
||||
style P fill:#FFD700
|
||||
style Q fill:#90EE90
|
||||
style C fill:#ADD8E6
|
||||
style G fill:#ADD8E6
|
||||
```
|
||||
|
||||
**Caption**: Technical review workflow performs comprehensive accuracy, security, and best practices validation.
|
||||
|
||||
**Time Estimate**: 3-6 hours per chapter
|
||||
**Agents Involved**: Technical Reviewer
|
||||
|
||||
**Review Criteria**:
|
||||
- Technical accuracy of all explanations
|
||||
- Code correctness and testing
|
||||
- Security vulnerabilities
|
||||
- Performance considerations
|
||||
- Best practices compliance
|
||||
- Cross-platform compatibility
|
||||
|
||||
---
|
||||
|
||||
### Incorporate Review Feedback Workflow
|
||||
|
||||
Apply technical reviewer feedback systematically.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Review Report Received] --> B[tutorial-architect: Read Review Report]
|
||||
B --> C[tutorial-architect: Categorize Issues]
|
||||
C --> D{Critical Issues?}
|
||||
D -->|Yes| E[tutorial-architect: Address Critical First]
|
||||
D -->|No| F[tutorial-architect: Address Major Issues]
|
||||
E --> G{Code Changes Needed?}
|
||||
F --> G
|
||||
G -->|Yes| H[code-curator: Update Code Examples]
|
||||
H --> I[code-curator: Re-test Code]
|
||||
I --> J{Tests Pass?}
|
||||
J -->|No| H
|
||||
J -->|Yes| K[tutorial-architect: Update Documentation]
|
||||
G -->|No| K
|
||||
K --> L[tutorial-architect: Address Minor Issues]
|
||||
L --> M[tutorial-architect: Verify All Issues Addressed]
|
||||
M --> N{All Fixed?}
|
||||
N -->|No| O[Complete Remaining]
|
||||
O --> M
|
||||
N -->|Yes| P[Submit for Re-review]
|
||||
|
||||
style A fill:#FFD700
|
||||
style P fill:#90EE90
|
||||
style E fill:#FF6B6B
|
||||
style F fill:#FFD700
|
||||
style K fill:#FFE4B5
|
||||
```
|
||||
|
||||
**Caption**: Feedback incorporation workflow ensures all review issues are systematically addressed and verified.
|
||||
|
||||
**Time Estimate**: 2-8 hours depending on issues
|
||||
**Agents Involved**: Tutorial Architect, Code Curator
|
||||
|
||||
---
|
||||
|
||||
## Publishing Workflows
|
||||
|
||||
### Publishing Decision Tree
|
||||
|
||||
Choose the right publishing workflow based on your target publisher.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Ready to Publish] --> B{Publisher Type?}
|
||||
B -->|PacktPub| C[packtpub-submission-workflow]
|
||||
B -->|O'Reilly| D[oreilly-submission-workflow]
|
||||
B -->|Manning| E{MEAP or Final?}
|
||||
B -->|Self-Publishing| F{Platform?}
|
||||
|
||||
E -->|MEAP| G[manning-meap-workflow]
|
||||
E -->|Final| H[manning-submission-workflow]
|
||||
|
||||
F -->|Leanpub| I[self-publishing-workflow: Leanpub]
|
||||
F -->|Amazon KDP| J[self-publishing-workflow: KDP]
|
||||
F -->|Gumroad| K[self-publishing-workflow: Gumroad]
|
||||
|
||||
C --> L[PacktPub Submission Package]
|
||||
D --> M[O'Reilly Submission Package]
|
||||
G --> N[Manning MEAP Release]
|
||||
H --> O[Manning Final Submission]
|
||||
I --> P[Leanpub Manuscript]
|
||||
J --> Q[KDP Manuscript]
|
||||
K --> R[Gumroad Package]
|
||||
|
||||
style A fill:#FFD700
|
||||
style L fill:#90EE90
|
||||
style M fill:#90EE90
|
||||
style N fill:#90EE90
|
||||
style O fill:#90EE90
|
||||
style P fill:#90EE90
|
||||
style Q fill:#90EE90
|
||||
style R fill:#90EE90
|
||||
```
|
||||
|
||||
**Caption**: Publishing decision tree guides you to the correct submission workflow based on your publisher.
|
||||
|
||||
---
|
||||
|
||||
### PacktPub Submission Workflow
|
||||
|
||||
Prepare manuscript for PacktPub submission.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Manuscript Complete] --> B[book-publisher: Gather All Chapters]
|
||||
B --> C[book-publisher: Format to PacktPub Standards]
|
||||
C --> D[book-publisher: Create Front Matter]
|
||||
D --> E[book-publisher: Create Back Matter]
|
||||
E --> F[api-documenter: Generate Appendices]
|
||||
F --> G[book-publisher: Package Code Repository]
|
||||
G --> H[screenshot-specialist: Prepare Visual Assets]
|
||||
H --> I[book-publisher: Run PacktPub Checklist]
|
||||
I --> J{Meets All Requirements?}
|
||||
J -->|No| K[Address Missing Items]
|
||||
K --> I
|
||||
J -->|Yes| L[book-publisher: Create Submission Package]
|
||||
L --> M[Ready for PacktPub Submission]
|
||||
|
||||
C -.-> C1[packtpub-format-guidelines]
|
||||
I -.-> I1[packtpub-submission-checklist]
|
||||
|
||||
style A fill:#FFD700
|
||||
style M fill:#90EE90
|
||||
style C fill:#FFE4B5
|
||||
style I fill:#F0E68C
|
||||
```
|
||||
|
||||
**Caption**: PacktPub submission workflow formats manuscript to publisher standards and creates complete submission package.
|
||||
|
||||
**Time Estimate**: 6-10 hours
|
||||
**Agents Involved**: Book Publisher, API Documenter, Screenshot Specialist
|
||||
|
||||
---
|
||||
|
||||
### O'Reilly Submission Workflow
|
||||
|
||||
Prepare manuscript for O'Reilly submission.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Manuscript Complete] --> B[book-publisher: Convert to AsciiDoc/HTMLBook]
|
||||
B --> C[book-publisher: Validate O'Reilly Format]
|
||||
C --> D{Format Valid?}
|
||||
D -->|Issues| E[Fix Format Issues]
|
||||
E --> C
|
||||
D -->|Valid| F[book-publisher: Create Atlas Project]
|
||||
F --> G[api-documenter: Generate Index]
|
||||
G --> H[screenshot-specialist: Prepare Images]
|
||||
H --> I[book-publisher: Setup Code Repository]
|
||||
I --> J[book-publisher: Run O'Reilly Checklist]
|
||||
J --> K{Meets Requirements?}
|
||||
K -->|No| L[Address Requirements]
|
||||
L --> J
|
||||
K -->|Yes| M[Ready for O'Reilly Atlas]
|
||||
|
||||
B -.-> B1[oreilly-htmlbook-spec]
|
||||
J -.-> J1[oreilly-format-checklist]
|
||||
|
||||
style A fill:#FFD700
|
||||
style M fill:#90EE90
|
||||
style B fill:#FFE4B5
|
||||
style C fill:#ADD8E6
|
||||
```
|
||||
|
||||
**Caption**: O'Reilly submission workflow converts to HTMLBook format and prepares Atlas-compatible project.
|
||||
|
||||
**Time Estimate**: 8-12 hours
|
||||
**Agents Involved**: Book Publisher, API Documenter, Screenshot Specialist
|
||||
|
||||
---
|
||||
|
||||
### Manning MEAP Workflow
|
||||
|
||||
Prepare chapter for Manning Early Access Program (MEAP).
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Chapter Complete] --> B[book-publisher: Format to Manning Standards]
|
||||
B --> C[book-publisher: Create Chapter Introduction]
|
||||
C --> D[book-publisher: Prepare MEAP Metadata]
|
||||
D --> E[screenshot-specialist: Optimize Images]
|
||||
E --> F[code-curator: Package Chapter Code]
|
||||
F --> G[book-publisher: Run MEAP Checklist]
|
||||
G --> H{MEAP Ready?}
|
||||
H -->|Issues| I[Fix MEAP Issues]
|
||||
I --> G
|
||||
H -->|Yes| J[book-publisher: Submit to Manning]
|
||||
J --> K[MEAP Chapter Released]
|
||||
|
||||
B -.-> B1[manning-format-guidelines]
|
||||
G -.-> G1[manning-meap-checklist]
|
||||
|
||||
style A fill:#FFD700
|
||||
style K fill:#90EE90
|
||||
style B fill:#FFE4B5
|
||||
style G fill:#F0E68C
|
||||
```
|
||||
|
||||
**Caption**: Manning MEAP workflow prepares individual chapters for early access release.
|
||||
|
||||
**Time Estimate**: 3-5 hours per chapter
|
||||
**Agents Involved**: Book Publisher, Screenshot Specialist, Code Curator
|
||||
|
||||
---
|
||||
|
||||
### Self-Publishing Workflow
|
||||
|
||||
Prepare manuscript for self-publishing platforms.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Manuscript Complete] --> B{Platform?}
|
||||
B -->|Leanpub| C[book-publisher: Convert to Leanpub Markdown]
|
||||
B -->|Amazon KDP| D[book-publisher: Convert to KDP Format]
|
||||
B -->|Gumroad| E[book-publisher: Convert to PDF/ePub]
|
||||
|
||||
C --> F[book-publisher: Setup Leanpub Project]
|
||||
D --> G[book-publisher: Create KDP Package]
|
||||
E --> H[book-publisher: Create Gumroad Package]
|
||||
|
||||
F --> I[book-publisher: Configure Pricing]
|
||||
G --> I
|
||||
H --> I
|
||||
|
||||
I --> J[book-publisher: Create Marketing Materials]
|
||||
J --> K[screenshot-specialist: Create Cover/Graphics]
|
||||
K --> L[book-publisher: Run Self-Publishing Checklist]
|
||||
L --> M{Ready to Publish?}
|
||||
M -->|No| N[Address Items]
|
||||
N --> L
|
||||
M -->|Yes| O[Ready for Self-Publishing]
|
||||
|
||||
L -.-> L1[self-publishing-standards-checklist]
|
||||
|
||||
style A fill:#FFD700
|
||||
style O fill:#90EE90
|
||||
style C fill:#FFE4B5
|
||||
style D fill:#FFE4B5
|
||||
style E fill:#FFE4B5
|
||||
```
|
||||
|
||||
**Caption**: Self-publishing workflow supports multiple platforms with format conversion and marketing materials.
|
||||
|
||||
**Time Estimate**: 8-15 hours
|
||||
**Agents Involved**: Book Publisher, Screenshot Specialist
|
||||
|
||||
---
|
||||
|
||||
## Brownfield Workflows
|
||||
|
||||
### Book Edition Update Workflow
|
||||
|
||||
Systematic approach to 2nd/3rd edition updates.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Existing Book] --> B[book-analyst: Analyze Current Edition]
|
||||
B --> C[book-analyst: Identify Changes Needed]
|
||||
C --> D[book-analyst: Create Revision Plan]
|
||||
D --> E{Scope of Changes?}
|
||||
E -->|Major| F[Full Restructure Needed]
|
||||
E -->|Moderate| G[Chapter Updates]
|
||||
E -->|Minor| H[Section Updates]
|
||||
|
||||
F --> I[instructional-designer: Redesign Structure]
|
||||
G --> J[Select Chapters to Update]
|
||||
H --> K[Select Sections to Update]
|
||||
|
||||
I --> L[Execute Greenfield Workflows]
|
||||
J --> L
|
||||
K --> L
|
||||
|
||||
L --> M[version-manager: Update Version References]
|
||||
M --> N[code-curator: Update All Code Examples]
|
||||
N --> O[technical-reviewer: Verify Changes]
|
||||
O --> P{Review Passed?}
|
||||
P -->|Issues| Q[Address Issues]
|
||||
Q --> O
|
||||
P -->|Approved| R[technical-editor: Ensure Consistency]
|
||||
R --> S[Updated Edition Complete]
|
||||
|
||||
B -.-> B1[book-analysis-report-tmpl]
|
||||
D -.-> D1[revision-plan-tmpl]
|
||||
O -.-> O1[revision-completeness-checklist]
|
||||
|
||||
style A fill:#FFD700
|
||||
style S fill:#90EE90
|
||||
style B fill:#FFE4B5
|
||||
style N fill:#FFE4B5
|
||||
style O fill:#ADD8E6
|
||||
```
|
||||
|
||||
**Caption**: Book edition update workflow analyzes existing content and systematically applies updates for new edition.
|
||||
|
||||
**Time Estimate**: 40-120+ hours depending on scope
|
||||
**Agents Involved**: Book Analyst, Instructional Designer, Code Curator, Version Manager, Technical Reviewer, Technical Editor
|
||||
|
||||
---
|
||||
|
||||
### Add Chapter to Existing Book Workflow
|
||||
|
||||
Add new chapter to already-published book.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[New Chapter Needed] --> B[book-analyst: Analyze Existing Book]
|
||||
B --> C[book-analyst: Determine Chapter Position]
|
||||
C --> D[instructional-designer: Design Chapter]
|
||||
D --> E[instructional-designer: Validate Prerequisites]
|
||||
E --> F{Prerequisites Available?}
|
||||
F -->|Missing| G[Update Earlier Chapters]
|
||||
F -->|Available| H[Execute Chapter Development]
|
||||
G --> H
|
||||
H --> I[Chapter Complete]
|
||||
I --> J[technical-editor: Update Book Structure]
|
||||
J --> K[technical-editor: Update Cross-References]
|
||||
K --> L[technical-editor: Update TOC/Index]
|
||||
L --> M[book-publisher: Integration Check]
|
||||
M --> N{Integrates Smoothly?}
|
||||
N -->|Issues| O[Fix Integration Issues]
|
||||
O --> M
|
||||
N -->|Success| P[New Chapter Integrated]
|
||||
|
||||
B -.-> B1[existing-book-integration-checklist]
|
||||
E -.-> E1[prerequisite-clarity-checklist]
|
||||
|
||||
style A fill:#FFD700
|
||||
style P fill:#90EE90
|
||||
style D fill:#FFE4B5
|
||||
style H fill:#FFE4B5
|
||||
style J fill:#ADD8E6
|
||||
```
|
||||
|
||||
**Caption**: Add chapter workflow ensures new chapter integrates seamlessly with existing book structure and content.
|
||||
|
||||
**Time Estimate**: 20-40 hours
|
||||
**Agents Involved**: Book Analyst, Instructional Designer, Tutorial Architect, Code Curator, Technical Editor, Book Publisher
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
These process flows visualize the complete technical book authoring system:
|
||||
|
||||
**High-Level Flows**:
|
||||
- Book Authoring Lifecycle - Complete journey from concept to published book
|
||||
- Agent Collaboration Map - How agents work together
|
||||
|
||||
**Planning**:
|
||||
- Book Planning Workflow - Create pedagogically sound outline
|
||||
|
||||
**Development**:
|
||||
- Section-Driven Development - Incremental chapter creation
|
||||
- Section Development - Core content creation unit
|
||||
- Chapter Assembly - Merge sections into chapters
|
||||
- Tutorial Creation - Hands-on learning experiences
|
||||
- Code Example Workflow - Quality code development
|
||||
|
||||
**Review**:
|
||||
- Technical Review - Comprehensive accuracy validation
|
||||
- Incorporate Feedback - Systematic issue resolution
|
||||
|
||||
**Publishing**:
|
||||
- Publishing Decision Tree - Choose right workflow
|
||||
- Publisher-Specific Workflows - PacktPub, O'Reilly, Manning, Self-Publishing
|
||||
|
||||
**Brownfield**:
|
||||
- Edition Updates - Systematic revision process
|
||||
- Add Chapters - Integrate new content
|
||||
|
||||
**Next Steps**:
|
||||
- **Start writing**: Follow [Getting Started Tutorial](getting-started.md)
|
||||
- **Deep dive on agents**: Read [Agent Reference](agent-reference.md)
|
||||
- **Choose workflows**: See [Workflow Guide](workflow-guide.md)
|
||||
- **See templates**: Explore [Template Gallery](template-gallery.md)
|
||||
|
||||
---
|
||||
|
||||
*Process Flows - Technical Writing Expansion Pack v1.1.0*
|
||||
|
|
@ -0,0 +1,243 @@
|
|||
# Quick Reference Card - Technical Writing Expansion Pack
|
||||
|
||||
One-page cheat sheet for most common workflows, agents, and commands.
|
||||
|
||||
## Quick Start Command Sequence
|
||||
|
||||
**For Writing Your First Chapter**:
|
||||
|
||||
```
|
||||
1. /bmad-tw:instructional-designer
|
||||
→ *create-book-outline
|
||||
|
||||
2. /bmad-tw:instructional-designer
|
||||
→ *create-chapter-outline
|
||||
|
||||
3. /bmad-tw:tutorial-architect
|
||||
→ *outline-section (repeat for each section)
|
||||
|
||||
4. /bmad-tw:code-curator
|
||||
→ *create-code-example
|
||||
|
||||
5. /bmad-tw:tutorial-architect
|
||||
→ *create-tutorial (write section content)
|
||||
|
||||
6. /bmad-tw:technical-reviewer
|
||||
→ *review-section
|
||||
|
||||
7. /bmad-tw:technical-editor
|
||||
→ *assemble-chapter
|
||||
|
||||
8. /bmad-tw:book-publisher
|
||||
→ *run-workflow packtpub-submission
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Top 5 Workflows
|
||||
|
||||
| # | Workflow | Use When | Time |
|
||||
|---|----------|----------|------|
|
||||
| 1 | **book-planning-workflow** | Starting new book, need approved outline | 20-33 hrs |
|
||||
| 2 | **section-development-workflow** | Writing one section (2-5 pages) | 5-10 hrs |
|
||||
| 3 | **chapter-assembly-workflow** | Merging sections into complete chapter | 4-6 hrs |
|
||||
| 4 | **technical-review-workflow** | Validating technical accuracy | 3-6 hrs |
|
||||
| 5 | **packtpub-submission-workflow** | Preparing for PacktPub submission | 6-10 hrs |
|
||||
|
||||
---
|
||||
|
||||
## Top 5 Agents
|
||||
|
||||
| # | Agent | Purpose | Key Commands |
|
||||
|---|-------|---------|--------------|
|
||||
| 1 | **Instructional Designer** 🎓 | Plan learning objectives, book structure | `*create-book-outline`<br>`*create-chapter-outline`<br>`*design-learning-path` |
|
||||
| 2 | **Tutorial Architect** 📝 | Write tutorials, hands-on content | `*create-tutorial`<br>`*write-walkthrough`<br>`*design-exercises` |
|
||||
| 3 | **Code Curator** 💻 | Create, test code examples | `*create-code-example`<br>`*test-code-examples`<br>`*setup-code-repository` |
|
||||
| 4 | **Technical Reviewer** 🔍 | Verify technical accuracy, security | `*review-chapter`<br>`*audit-security`<br>`*verify-best-practices` |
|
||||
| 5 | **Technical Editor** ✍️ | Polish writing, ensure consistency | `*assemble-chapter`<br>`*improve-clarity`<br>`*check-accessibility` |
|
||||
|
||||
---
|
||||
|
||||
## Top 5 Checklists
|
||||
|
||||
| # | Checklist | Use When | Purpose |
|
||||
|---|-----------|----------|---------|
|
||||
| 1 | **chapter-completeness-checklist** | After chapter assembly | Ensure all required elements present |
|
||||
| 2 | **code-quality-checklist** | After code development | Verify code standards met |
|
||||
| 3 | **technical-accuracy-checklist** | During technical review | Validate correctness |
|
||||
| 4 | **packtpub-submission-checklist** | Before publisher submission | Ensure PacktPub compliance |
|
||||
| 5 | **final-manuscript-checklist** | Before final submission | Complete manuscript validation |
|
||||
|
||||
---
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Agent Control
|
||||
- `*help` - Show agent's available commands
|
||||
- `*exit` - Exit current agent
|
||||
|
||||
### Document Creation
|
||||
- `*create-doc <template>` - Create document from template
|
||||
- `*create-book-outline` - Design book structure
|
||||
- `*create-chapter-outline` - Plan chapter sections
|
||||
- `*create-tutorial` - Write hands-on tutorial
|
||||
|
||||
### Quality Assurance
|
||||
- `*execute-checklist <checklist>` - Run quality check
|
||||
- `*review-chapter` - Technical accuracy review
|
||||
- `*test-code-examples` - Verify code works
|
||||
|
||||
### Publishing
|
||||
- `*run-workflow <workflow>` - Execute publishing workflow
|
||||
- `*package-for-publisher` - Prepare submission
|
||||
- `*format-manuscript` - Apply publisher standards
|
||||
|
||||
---
|
||||
|
||||
## Decision Trees
|
||||
|
||||
### Which Workflow Should I Use?
|
||||
|
||||
**I want to...**
|
||||
- **Plan a new book** → `book-planning-workflow`
|
||||
- **Write one section** → `section-development-workflow`
|
||||
- **Complete a whole chapter** → `chapter-development-workflow`
|
||||
- **Review content** → `technical-review-workflow`
|
||||
- **Submit to PacktPub** → `packtpub-submission-workflow`
|
||||
- **Submit to O'Reilly** → `oreilly-submission-workflow`
|
||||
- **Submit to Manning** → `manning-meap-workflow`
|
||||
- **Self-publish** → `self-publishing-workflow`
|
||||
- **Update 2nd edition** → `book-edition-update-workflow`
|
||||
- **Add chapter to existing book** → `add-chapter-to-existing-book-workflow`
|
||||
|
||||
### Which Agent Should I Use?
|
||||
|
||||
**I want to...**
|
||||
- **Design learning outcomes** → Instructional Designer
|
||||
- **Write tutorials** → Tutorial Architect
|
||||
- **Create code examples** → Code Curator
|
||||
- **Check technical accuracy** → Technical Reviewer
|
||||
- **Polish writing** → Technical Editor
|
||||
- **Prepare for publishing** → Book Publisher
|
||||
- **Document APIs** → API Documenter
|
||||
- **Create diagrams** → Screenshot Specialist
|
||||
- **Design exercises** → Exercise Creator
|
||||
- **Update existing book** → Book Analyst
|
||||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
your-book-project/
|
||||
├── docs/
|
||||
│ ├── planning/
|
||||
│ │ ├── book-outline.md
|
||||
│ │ └── chapter-outlines/
|
||||
│ ├── sections/
|
||||
│ │ └── chapter-01/
|
||||
│ │ ├── section-1.1.md
|
||||
│ │ └── section-1.2.md
|
||||
│ ├── chapters/
|
||||
│ │ └── chapter-01.md
|
||||
│ └── reviews/
|
||||
│ └── chapter-01-review.md
|
||||
├── code-examples/
|
||||
│ └── chapter-01/
|
||||
└── submission/
|
||||
└── packtpub/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Typical Time Estimates
|
||||
|
||||
| Activity | Time |
|
||||
|----------|------|
|
||||
| Book planning (outline) | 20-33 hrs |
|
||||
| Chapter outline | 3-5 hrs |
|
||||
| Section writing (2-5 pages) | 5-10 hrs |
|
||||
| Code example development | 1-3 hrs |
|
||||
| Technical review (chapter) | 3-6 hrs |
|
||||
| Chapter assembly | 4-6 hrs |
|
||||
| Publisher submission prep | 6-10 hrs |
|
||||
| **Complete chapter (6 sections)** | **40-70 hrs** |
|
||||
|
||||
---
|
||||
|
||||
## Section-Driven Development Summary
|
||||
|
||||
**Break chapters into 2-5 page sections**:
|
||||
|
||||
1. **Plan Sections** - Instructional Designer creates section list
|
||||
2. **Write Each Section** - Tutorial Architect + Code Curator
|
||||
3. **Review Sections** - Technical Reviewer validates
|
||||
4. **Assemble Chapter** - Technical Editor merges
|
||||
|
||||
**Benefits**:
|
||||
- Manageable scope (small chunks)
|
||||
- Parallel development possible
|
||||
- Incremental progress visible
|
||||
- Quality easier to maintain
|
||||
|
||||
---
|
||||
|
||||
## Quality Gates
|
||||
|
||||
### Must Pass Before Moving Forward
|
||||
|
||||
**After Book Outline**:
|
||||
- ✅ All chapters have clear learning objectives
|
||||
- ✅ Prerequisites flow logically
|
||||
- ✅ No knowledge gaps between chapters
|
||||
|
||||
**After Section Development**:
|
||||
- ✅ Code examples tested and working
|
||||
- ✅ Technical review approved
|
||||
- ✅ 2-5 pages length appropriate
|
||||
- ✅ Learning objectives met
|
||||
|
||||
**After Chapter Assembly**:
|
||||
- ✅ Smooth transitions between sections
|
||||
- ✅ Introduction and summary present
|
||||
- ✅ Cross-references validated
|
||||
- ✅ Consistent style throughout
|
||||
|
||||
**Before Publisher Submission**:
|
||||
- ✅ All checklists passed
|
||||
- ✅ Code repository complete
|
||||
- ✅ Images/diagrams optimized
|
||||
- ✅ Publisher format requirements met
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### New to BMad Technical Writing?
|
||||
1. Read [Getting Started Tutorial](getting-started.md) - 1-2 hours hands-on
|
||||
2. Review [User Guide](user-guide.md) - Conceptual overview
|
||||
3. Start writing your first section!
|
||||
|
||||
### Ready to Go Deep?
|
||||
- [Process Flows](process-flows.md) - Visual workflow diagrams
|
||||
- [Agent Reference](agent-reference.md) - All 13 agents detailed
|
||||
- [Workflow Guide](workflow-guide.md) - Complete workflow documentation
|
||||
- [Template Gallery](template-gallery.md) - All templates with examples
|
||||
|
||||
### Need Help?
|
||||
- [Troubleshooting Guide](troubleshooting.md) - Common issues
|
||||
- [FAQ](faq.md) - Frequently asked questions
|
||||
- [Discord Community](https://discord.gg/gk8jAdXWmj) - Get support
|
||||
- [GitHub Issues](https://github.com/bmadcode/bmad-method/issues) - Report bugs
|
||||
|
||||
---
|
||||
|
||||
## Print-Friendly Version
|
||||
|
||||
**Save this page as PDF for quick reference while writing!**
|
||||
|
||||
---
|
||||
|
||||
*Quick Reference Card - Technical Writing Expansion Pack v1.1.0*
|
||||
*Keep this handy while writing your technical book*
|
||||
|
|
@ -0,0 +1,201 @@
|
|||
# Troubleshooting Guide - Technical Writing Expansion Pack
|
||||
|
||||
Common issues and solutions for the BMad Technical Writing Expansion Pack.
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### Issue: "Expansion pack not found"
|
||||
**Symptom**: Cannot activate agents, "bmad-technical-writing not found" error
|
||||
|
||||
**Cause**: Expansion pack not installed or not in correct location
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Verify installation
|
||||
ls ~/.bmad-method/expansion-packs/bmad-technical-writing
|
||||
|
||||
# If missing, reinstall
|
||||
npx bmad-method install
|
||||
# Select "Technical Book Writing Studio"
|
||||
```
|
||||
|
||||
### Issue: "Dependencies not resolving"
|
||||
**Symptom**: Agent activation fails with missing template/task errors
|
||||
|
||||
**Cause**: Incomplete installation or corrupted files
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Reinstall expansion pack
|
||||
npx bmad-method install --force
|
||||
```
|
||||
|
||||
## Agent Activation Issues
|
||||
|
||||
### Issue: "Agent not responding"
|
||||
**Symptom**: Agent activates but doesn't respond to commands
|
||||
|
||||
**Cause**: AI context limit reached or agent definition not loaded
|
||||
|
||||
**Solution**:
|
||||
1. Check agent loaded correctly (should show persona description)
|
||||
2. Try `*help` command to see available commands
|
||||
3. If still unresponsive, re-activate agent
|
||||
|
||||
### Issue: "Commands not recognized"
|
||||
**Symptom**: Agent doesn't recognize `*command-name`
|
||||
|
||||
**Cause**: Typo in command or command doesn't exist for this agent
|
||||
|
||||
**Solution**:
|
||||
1. Run `*help` to see valid commands for current agent
|
||||
2. Check command spelling (commands are case-sensitive)
|
||||
3. Verify you're using correct agent for the task
|
||||
|
||||
### Issue: "Agent dependencies missing"
|
||||
**Symptom**: Agent can't find templates, tasks, or checklists
|
||||
|
||||
**Cause**: Files not in expected location
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Verify file structure
|
||||
ls expansion-packs/bmad-technical-writing/templates/
|
||||
ls expansion-packs/bmad-technical-writing/tasks/
|
||||
ls expansion-packs/bmad-technical-writing/checklists/
|
||||
```
|
||||
|
||||
## Workflow Execution Issues
|
||||
|
||||
### Issue: "Workflow fails at step X"
|
||||
**Symptom**: Workflow stops mid-execution with error
|
||||
|
||||
**Cause**: Missing prerequisite or validation failure
|
||||
|
||||
**Solution**:
|
||||
1. Check workflow prerequisites (see workflow YAML file)
|
||||
2. Verify previous steps completed successfully
|
||||
3. Review quality gates - ensure they passed
|
||||
|
||||
### Issue: "Inputs not accepted"
|
||||
**Symptom**: Workflow rejects provided inputs
|
||||
|
||||
**Cause**: Invalid format or missing required fields
|
||||
|
||||
**Solution**:
|
||||
1. Check template requirements (see template YAML file)
|
||||
2. Ensure all required fields provided
|
||||
3. Verify format matches expected structure
|
||||
|
||||
### Issue: "Outputs not produced"
|
||||
**Symptom**: Workflow completes but output file not created
|
||||
|
||||
**Cause**: File path issue or write permissions
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check directory exists
|
||||
mkdir -p docs/planning docs/sections docs/chapters
|
||||
|
||||
# Check write permissions
|
||||
ls -la docs/
|
||||
```
|
||||
|
||||
## Build/Validation Errors
|
||||
|
||||
### Issue: "npm run validate fails"
|
||||
**Symptom**: Validation command reports errors
|
||||
|
||||
**Cause**: Invalid YAML syntax or missing required fields
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# See specific errors
|
||||
npm run validate
|
||||
|
||||
# Common fixes:
|
||||
# - Check YAML indentation (use spaces, not tabs)
|
||||
# - Verify all required fields present
|
||||
# - Check for typos in agent/workflow references
|
||||
```
|
||||
|
||||
### Issue: "YAML syntax error"
|
||||
**Symptom**: Parse error when loading configuration
|
||||
|
||||
**Cause**: Invalid YAML formatting
|
||||
|
||||
**Solution**:
|
||||
1. Check indentation (2 spaces per level)
|
||||
2. Verify no tabs used (YAML requires spaces)
|
||||
3. Check quotes around special characters
|
||||
4. Use YAML validator online
|
||||
|
||||
## Integration Issues
|
||||
|
||||
### Issue: "Conflicts with core BMad"
|
||||
**Symptom**: Agents or commands conflict
|
||||
|
||||
**Cause**: Name collision or incompatible versions
|
||||
|
||||
**Solution**:
|
||||
1. Use full agent IDs: `/bmad-tw:agent-name`
|
||||
2. Update both core and expansion pack to latest versions
|
||||
|
||||
### Issue: "Multi-expansion conflicts"
|
||||
**Symptom**: Multiple expansion packs interfere with each other
|
||||
|
||||
**Cause**: Agent name collisions
|
||||
|
||||
**Solution**:
|
||||
1. Use full qualified names: `/bmad-tw:agent` vs `/bmad-cw:agent`
|
||||
2. Activate only needed agents
|
||||
|
||||
## General Troubleshooting Tips
|
||||
|
||||
### Check Logs
|
||||
```bash
|
||||
# View debug logs if available
|
||||
cat .ai/debug-log.md
|
||||
```
|
||||
|
||||
### Verify Installation
|
||||
```bash
|
||||
# Check all required files present
|
||||
npm run validate
|
||||
```
|
||||
|
||||
### Update to Latest Version
|
||||
```bash
|
||||
# Pull latest changes
|
||||
git pull origin main
|
||||
|
||||
# Rebuild
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Clear Cache
|
||||
```bash
|
||||
# Remove dist files and rebuild
|
||||
rm -rf dist/
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
If your issue isn't listed here:
|
||||
|
||||
1. **Check Documentation**
|
||||
- [User Guide](user-guide.md) - System overview
|
||||
- [FAQ](faq.md) - Common questions
|
||||
|
||||
2. **Community Support**
|
||||
- [Discord](https://discord.gg/gk8jAdXWmj) - Real-time help
|
||||
- [GitHub Discussions](https://github.com/bmadcode/bmad-method/discussions) - Q&A
|
||||
|
||||
3. **Report Bugs**
|
||||
- [GitHub Issues](https://github.com/bmadcode/bmad-method/issues) - Bug reports
|
||||
- Include: Error message, steps to reproduce, environment details
|
||||
|
||||
---
|
||||
|
||||
*Troubleshooting Guide - Technical Writing Expansion Pack v1.1.0*
|
||||
|
|
@ -0,0 +1,871 @@
|
|||
# BMad Technical Writing Expansion Pack - User Guide
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [What is the Technical Writing Expansion Pack?](#what-is-the-technical-writing-expansion-pack)
|
||||
- [Who is This For?](#who-is-this-for)
|
||||
- [What Can You Build With It?](#what-can-you-build-with-it)
|
||||
- [How Does It Work With BMad Core?](#how-does-it-work-with-bmad-core)
|
||||
- [Core Concepts](#core-concepts)
|
||||
- [Book Authoring Lifecycle](#book-authoring-lifecycle)
|
||||
- [Agent System](#agent-system)
|
||||
- [Workflow Orchestration](#workflow-orchestration)
|
||||
- [Section-Driven Development](#section-driven-development)
|
||||
- [Greenfield vs Brownfield Approaches](#greenfield-vs-brownfield-approaches)
|
||||
- [Architecture](#architecture)
|
||||
- [System Components](#system-components)
|
||||
- [Dependencies](#dependencies)
|
||||
- [Build System](#build-system)
|
||||
- [Web UI vs IDE Usage](#web-ui-vs-ide-usage)
|
||||
- [Agents](#agents)
|
||||
- [Workflows](#workflows)
|
||||
- [Templates](#templates)
|
||||
- [Tasks](#tasks)
|
||||
- [Checklists](#checklists)
|
||||
- [Getting Started](#getting-started)
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
### What is the Technical Writing Expansion Pack?
|
||||
|
||||
The Technical Writing Expansion Pack transforms BMad-Method into a complete technical book writing studio. It extends the core BMad framework with specialized agents, workflows, and quality assurance tools specifically designed for technical book authors, technical trainers, and documentation specialists.
|
||||
|
||||
Think of it as hiring a complete publishing team:
|
||||
- **Learning architects** who design effective pedagogical structures
|
||||
- **Technical writers** who craft clear, engaging tutorials
|
||||
- **Code experts** who create and maintain working examples
|
||||
- **Reviewers** who ensure technical accuracy and security
|
||||
- **Editors** who polish your prose and ensure publisher compliance
|
||||
- **Publishing specialists** who prepare manuscripts for submission
|
||||
|
||||
All working together in an AI-powered framework built entirely in natural language (markdown and YAML).
|
||||
|
||||
**Version**: 1.1.0
|
||||
**Package Name**: `bmad-technical-writing`
|
||||
**Agents**: 13 (10 required + 3 optional)
|
||||
**Workflows**: 15
|
||||
**Templates**: 18
|
||||
**Tasks**: 33
|
||||
**Checklists**: 31
|
||||
|
||||
### Who is This For?
|
||||
|
||||
This expansion pack is designed for:
|
||||
|
||||
- **Technical book authors** writing for publishers like PacktPub, O'Reilly, Manning, or Pragmatic Bookshelf
|
||||
- **Self-published authors** creating technical content for platforms like Leanpub, Amazon KDP, or Gumroad
|
||||
- **Technical trainers** developing comprehensive course materials with code examples
|
||||
- **Documentation specialists** creating extensive technical documentation with tutorials
|
||||
- **Open source maintainers** writing project documentation and getting-started guides
|
||||
- **Developer advocates** creating technical content and learning resources
|
||||
|
||||
You should have:
|
||||
- Basic understanding of your technical subject matter
|
||||
- Familiarity with markdown formatting
|
||||
- Access to an AI chat interface (Gemini, ChatGPT, Claude) or IDE with AI (Cursor, VS Code, Claude Code)
|
||||
- BMad-Method core installed
|
||||
|
||||
### What Can You Build With It?
|
||||
|
||||
The Technical Writing Expansion Pack supports:
|
||||
|
||||
**Technical Books**:
|
||||
- Programming language tutorials (Python, JavaScript, Go, Rust, etc.)
|
||||
- Framework guides (React, Django, Spring Boot, etc.)
|
||||
- Technology deep-dives (databases, cloud, DevOps, security)
|
||||
- Best practices and patterns books
|
||||
- Reference manuals and API documentation
|
||||
|
||||
**Book Types**:
|
||||
- **Greenfield** - New books written from scratch
|
||||
- **Brownfield** - Second/third editions, version updates, chapter additions
|
||||
|
||||
**Publishing Targets**:
|
||||
- Traditional publishers (PacktPub, O'Reilly, Manning)
|
||||
- Self-publishing platforms (Leanpub, KDP, Gumroad)
|
||||
- Open source documentation
|
||||
- Corporate training materials
|
||||
|
||||
**Content Features**:
|
||||
- Hands-on tutorials with step-by-step instructions
|
||||
- Working code examples with testing infrastructure
|
||||
- Practice exercises and solutions
|
||||
- Technical diagrams and screenshots
|
||||
- API reference documentation
|
||||
- Learning objectives and prerequisites
|
||||
- Glossaries and appendices
|
||||
|
||||
### How Does It Work With BMad Core?
|
||||
|
||||
The Technical Writing Expansion Pack **extends** BMad-Method core with domain-specific capabilities:
|
||||
|
||||
**BMad Core Provides**:
|
||||
- Agent activation system
|
||||
- Task execution framework
|
||||
- Template processing engine
|
||||
- Dependency resolution
|
||||
- Build tools and validation
|
||||
- Configuration management
|
||||
|
||||
**Technical Writing Pack Adds**:
|
||||
- 13 specialized agents for book writing
|
||||
- 15 book authoring workflows
|
||||
- 18 publishing templates
|
||||
- 33 technical writing tasks
|
||||
- 31 quality assurance checklists
|
||||
- 6 knowledge bases (publisher guidelines, learning frameworks, etc.)
|
||||
|
||||
**Integration Pattern**:
|
||||
```
|
||||
BMad Core (Framework) + Technical Writing Pack (Domain Logic) = Complete Book Writing Studio
|
||||
```
|
||||
|
||||
You can also combine this pack with other expansion packs:
|
||||
- **Creative Writing Pack** - For books with narrative elements or fiction appendices
|
||||
- **Infrastructure Pack** - For DevOps and cloud infrastructure books
|
||||
|
||||
---
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Book Authoring Lifecycle
|
||||
|
||||
Technical book authoring follows a structured lifecycle with distinct phases:
|
||||
|
||||
#### 1. Planning Phase
|
||||
**Goal**: Design the learning experience and book structure
|
||||
|
||||
- Define target audience and prerequisites
|
||||
- Create learning objectives aligned with outcomes
|
||||
- Design book outline with chapter progression
|
||||
- Map prerequisite dependencies between chapters
|
||||
- Validate pedagogical structure
|
||||
|
||||
**Key Deliverables**: Book proposal, book outline, learning objectives
|
||||
|
||||
**Agents Involved**: Instructional Designer, Tutorial Architect, Book Publisher
|
||||
|
||||
#### 2. Drafting Phase
|
||||
**Goal**: Create chapter content with code examples and tutorials
|
||||
|
||||
- Design chapter outline with section breakdown
|
||||
- Write section content (2-5 pages per section)
|
||||
- Create working code examples
|
||||
- Develop practice exercises
|
||||
- Document expected outcomes and troubleshooting
|
||||
|
||||
**Key Deliverables**: Chapter drafts, code examples, exercise sets
|
||||
|
||||
**Agents Involved**: Tutorial Architect, Code Curator, Exercise Creator
|
||||
|
||||
#### 3. Review Phase
|
||||
**Goal**: Ensure technical accuracy, security, and quality
|
||||
|
||||
- Verify technical correctness of all content
|
||||
- Audit code examples for security vulnerabilities
|
||||
- Validate best practices and patterns
|
||||
- Check performance considerations
|
||||
- Test cross-platform compatibility
|
||||
|
||||
**Key Deliverables**: Technical review report, revision notes
|
||||
|
||||
**Agents Involved**: Technical Reviewer, Code Curator
|
||||
|
||||
#### 4. Editing Phase
|
||||
**Goal**: Polish writing and ensure publisher compliance
|
||||
|
||||
- Improve clarity and readability
|
||||
- Ensure consistent style and tone
|
||||
- Verify publisher formatting requirements
|
||||
- Check accessibility standards
|
||||
- Validate cross-references and citations
|
||||
|
||||
**Key Deliverables**: Polished manuscript, style corrections
|
||||
|
||||
**Agents Involved**: Technical Editor
|
||||
|
||||
#### 5. Publishing Phase
|
||||
**Goal**: Prepare and submit manuscript to publisher
|
||||
|
||||
- Package manuscript per publisher specifications
|
||||
- Create supplementary materials (preface, appendix, index, glossary)
|
||||
- Prepare code repositories
|
||||
- Generate submission materials
|
||||
- Handle MEAP/beta releases (Manning/Leanpub)
|
||||
|
||||
**Key Deliverables**: Submission package, code repository, supplementary materials
|
||||
|
||||
**Agents Involved**: Book Publisher, API Documenter, Screenshot Specialist
|
||||
|
||||
### Agent System
|
||||
|
||||
Agents are specialized AI personas that handle specific aspects of book authoring. Each agent has:
|
||||
|
||||
- **Defined role and expertise** - Clear responsibilities and domain knowledge
|
||||
- **Commands** - Specific actions the agent can perform
|
||||
- **Dependencies** - Templates, tasks, and checklists the agent uses
|
||||
- **Activation instructions** - How the agent initializes and operates
|
||||
|
||||
**Agent Categories**:
|
||||
|
||||
1. **Core Agents (10)** - Required for basic book authoring
|
||||
- Instructional Designer, Tutorial Architect, Code Curator
|
||||
- Technical Reviewer, Technical Editor, Book Publisher
|
||||
- API Documenter, Screenshot Specialist, Exercise Creator
|
||||
- Book Analyst (brownfield)
|
||||
|
||||
2. **Optional Agents (3)** - For advanced scenarios
|
||||
- Learning Path Designer (complex prerequisite mapping)
|
||||
- Sample Code Maintainer (extensive code repository management)
|
||||
- Version Manager (multi-version compatibility matrices)
|
||||
|
||||
**How Agents Work**:
|
||||
- Agents are activated using slash commands (e.g., `/bmad-tw:instructional-designer`)
|
||||
- Once activated, an agent loads its persona and presents available commands
|
||||
- Users select commands to execute specific tasks
|
||||
- Agents can call other agents via workflow orchestration
|
||||
- Agents stay in character until explicitly told to exit
|
||||
|
||||
**Agent Collaboration**:
|
||||
Agents collaborate through workflows. For example, in section-development-workflow:
|
||||
1. Tutorial Architect outlines the section
|
||||
2. Code Curator creates code examples
|
||||
3. Tutorial Architect writes tutorial content using the code
|
||||
4. Technical Reviewer verifies accuracy
|
||||
5. Tutorial Architect incorporates feedback
|
||||
|
||||
### Workflow Orchestration
|
||||
|
||||
Workflows are structured sequences that coordinate multiple agents to accomplish complex book authoring tasks.
|
||||
|
||||
**Workflow Structure** (YAML):
|
||||
```yaml
|
||||
workflow:
|
||||
name: section-development-workflow
|
||||
agents:
|
||||
primary: tutorial-architect
|
||||
supporting: [code-curator, technical-reviewer]
|
||||
steps:
|
||||
- agent: tutorial-architect
|
||||
task: outline-section
|
||||
- agent: code-curator
|
||||
task: create-code-examples
|
||||
- agent: tutorial-architect
|
||||
task: write-tutorial-content
|
||||
- agent: technical-reviewer
|
||||
task: review-section
|
||||
```
|
||||
|
||||
**Workflow Types**:
|
||||
|
||||
1. **Planning Workflows** - Structure and design
|
||||
- `book-planning-workflow` - Complete book planning from concept to outline
|
||||
|
||||
2. **Development Workflows** - Content creation
|
||||
- `section-planning-workflow` - Break chapter into sections
|
||||
- `section-development-workflow` - Write individual sections
|
||||
- `chapter-assembly-workflow` - Merge sections into complete chapter
|
||||
- `chapter-development-workflow` - Complete chapter creation
|
||||
- `tutorial-creation-workflow` - Hands-on tutorial development
|
||||
- `code-example-workflow` - Code example creation and testing
|
||||
|
||||
3. **Review Workflows** - Quality assurance
|
||||
- `technical-review-workflow` - Technical accuracy verification
|
||||
- `incorporate-review-feedback-workflow` - Apply reviewer feedback
|
||||
|
||||
4. **Publishing Workflows** - Submission preparation
|
||||
- `packtpub-submission-workflow` - PacktPub formatting and submission
|
||||
- `oreilly-submission-workflow` - O'Reilly standards compliance
|
||||
- `manning-meap-workflow` - Manning MEAP release preparation
|
||||
- `self-publishing-workflow` - Leanpub/KDP/Gumroad preparation
|
||||
|
||||
5. **Brownfield Workflows** - Existing book updates
|
||||
- `book-edition-update-workflow` - 2nd/3rd edition revisions
|
||||
- `add-chapter-to-existing-book-workflow` - Add chapters to existing books
|
||||
|
||||
**How Workflows Execute**:
|
||||
1. User activates primary agent
|
||||
2. User triggers workflow command
|
||||
3. Agent executes workflow steps sequentially
|
||||
4. Each step may involve tasks, templates, and checklists
|
||||
5. Agent may call supporting agents for specific steps
|
||||
6. Workflow completes with deliverable output
|
||||
|
||||
### Section-Driven Development
|
||||
|
||||
Section-driven development is the recommended approach for writing technical book chapters. It breaks chapters into small, manageable sections (2-5 pages each) that can be developed independently.
|
||||
|
||||
**Why Section-Driven?**
|
||||
|
||||
- **Manageable scope** - Small sections are easier to write and review
|
||||
- **Parallel development** - Multiple sections can be developed simultaneously
|
||||
- **Incremental progress** - Each section completion is a milestone
|
||||
- **Quality focus** - Easier to maintain quality in small chunks
|
||||
- **Flexibility** - Sections can be reordered or replaced without major rewrites
|
||||
|
||||
**Section-Driven Workflow**:
|
||||
|
||||
1. **Plan**: Instructional Designer creates chapter outline, breaks into 6-8 sections
|
||||
2. **Develop**: Tutorial Architect writes each section individually
|
||||
3. **Review**: Technical Reviewer validates each section
|
||||
4. **Assemble**: Technical Editor merges sections into cohesive chapter
|
||||
5. **Publish**: Book Publisher prepares final chapter for submission
|
||||
|
||||
**Section Structure**:
|
||||
- **Introduction** (0.5-1 page) - What you'll learn, prerequisites
|
||||
- **Concept Explanation** (1-2 pages) - Theory and context
|
||||
- **Hands-On Tutorial** (1-2 pages) - Step-by-step implementation
|
||||
- **Troubleshooting** (0.5-1 page) - Common issues and solutions
|
||||
- **Summary** (0.5 page) - Key takeaways, next steps
|
||||
|
||||
**Example Section Breakdown** (Chapter 3: Lists and Tuples):
|
||||
- Section 3.1: Introduction to Lists (3 pages)
|
||||
- Section 3.2: List Operations and Methods (4 pages)
|
||||
- Section 3.3: List Comprehensions (3 pages)
|
||||
- Section 3.4: Introduction to Tuples (3 pages)
|
||||
- Section 3.5: When to Use Lists vs Tuples (2 pages)
|
||||
- Section 3.6: Advanced List Techniques (4 pages)
|
||||
|
||||
### Greenfield vs Brownfield Approaches
|
||||
|
||||
**Greenfield** = New book written from scratch
|
||||
|
||||
**Use When**:
|
||||
- Starting a completely new book project
|
||||
- No existing content to work with
|
||||
- Clean slate for structure and design
|
||||
|
||||
**Agents Used**:
|
||||
- Instructional Designer (book planning)
|
||||
- Tutorial Architect (content creation)
|
||||
- Code Curator (code examples)
|
||||
- Technical Reviewer (accuracy)
|
||||
- Technical Editor (polish)
|
||||
- Book Publisher (submission)
|
||||
- Plus specialists (API Documenter, Screenshot Specialist, Exercise Creator)
|
||||
|
||||
**Workflows**:
|
||||
- book-planning-workflow
|
||||
- chapter-development-workflow
|
||||
- section-development-workflow
|
||||
- Publisher-specific submission workflows
|
||||
|
||||
---
|
||||
|
||||
**Brownfield** = Existing book updates, revisions, additions
|
||||
|
||||
**Use When**:
|
||||
- Writing 2nd or 3rd edition
|
||||
- Updating for new technology version (Python 3.10 → 3.12)
|
||||
- Adding chapters to existing book
|
||||
- Incorporating reviewer feedback
|
||||
- Migrating to new publisher
|
||||
|
||||
**Agents Used**:
|
||||
- Book Analyst (analyze existing content, plan revisions)
|
||||
- Plus all greenfield agents for new/updated content
|
||||
|
||||
**Workflows**:
|
||||
- book-edition-update-workflow
|
||||
- add-chapter-to-existing-book-workflow
|
||||
- incorporate-review-feedback-workflow
|
||||
|
||||
**Brownfield Process**:
|
||||
1. Book Analyst analyzes existing book structure and content
|
||||
2. Book Analyst creates revision plan (what needs updating/adding/removing)
|
||||
3. Greenfield agents execute revision plan for updated content
|
||||
4. Technical Editor ensures consistency between old and new content
|
||||
5. Book Publisher prepares updated manuscript
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### System Components
|
||||
|
||||
The Technical Writing Expansion Pack consists of five main component types:
|
||||
|
||||
#### 1. Agents (`agents/*.md`)
|
||||
Markdown files with embedded YAML configuration defining AI personas.
|
||||
|
||||
**Structure**:
|
||||
```markdown
|
||||
# agent-name
|
||||
|
||||
ACTIVATION-NOTICE: ...
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
name: Agent Name
|
||||
id: agent-id
|
||||
title: Agent Title
|
||||
icon: 🎓
|
||||
whenToUse: Description
|
||||
persona:
|
||||
role: Role description
|
||||
style: Communication style
|
||||
identity: Expertise areas
|
||||
focus: Primary focus
|
||||
commands:
|
||||
- command-name: description
|
||||
dependencies:
|
||||
tasks: [...]
|
||||
templates: [...]
|
||||
checklists: [...]
|
||||
data: [...]
|
||||
```
|
||||
|
||||
## Startup Context
|
||||
|
||||
Detailed persona instructions...
|
||||
```
|
||||
|
||||
#### 2. Workflows (`workflows/*.yaml`)
|
||||
YAML files defining multi-agent orchestration sequences.
|
||||
|
||||
**Structure**:
|
||||
```yaml
|
||||
workflow:
|
||||
name: workflow-name
|
||||
description: Workflow description
|
||||
agents:
|
||||
primary: agent-id
|
||||
supporting: [agent-id, ...]
|
||||
steps:
|
||||
- step: 1
|
||||
agent: agent-id
|
||||
task: task-name
|
||||
template: template-name
|
||||
checklist: checklist-name
|
||||
- step: 2
|
||||
...
|
||||
outputs:
|
||||
- output-name
|
||||
```
|
||||
|
||||
#### 3. Templates (`templates/*.yaml`)
|
||||
YAML files defining document structures with sections and LLM instructions.
|
||||
|
||||
**Structure**:
|
||||
```yaml
|
||||
template:
|
||||
name: template-name
|
||||
description: Template description
|
||||
elicit: true/false
|
||||
elicitation:
|
||||
prompts:
|
||||
- prompt: Question to ask user
|
||||
id: variable-name
|
||||
output:
|
||||
sections:
|
||||
- section: Section Name
|
||||
instructions: LLM instructions for section
|
||||
content: Template content with {{variables}}
|
||||
```
|
||||
|
||||
#### 4. Tasks (`tasks/*.md`)
|
||||
Markdown files with step-by-step executable instructions.
|
||||
|
||||
**Structure**:
|
||||
```markdown
|
||||
# task-name
|
||||
|
||||
## Purpose
|
||||
What this task accomplishes
|
||||
|
||||
## Inputs
|
||||
What's needed to start
|
||||
|
||||
## Steps
|
||||
1. Step one
|
||||
2. Step two
|
||||
...
|
||||
|
||||
## Outputs
|
||||
What this task produces
|
||||
|
||||
## Success Criteria
|
||||
How to know task is complete
|
||||
```
|
||||
|
||||
#### 5. Checklists (`checklists/*.md`)
|
||||
Markdown files with quality assurance criteria.
|
||||
|
||||
**Structure**:
|
||||
```markdown
|
||||
# checklist-name
|
||||
|
||||
## Purpose
|
||||
What this checklist validates
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
...
|
||||
|
||||
## Pass Criteria
|
||||
All items must be checked
|
||||
```
|
||||
|
||||
### Dependencies
|
||||
|
||||
Agents declare dependencies on templates, tasks, checklists, and data:
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
tasks:
|
||||
- create-doc.md
|
||||
- design-book-outline.md
|
||||
templates:
|
||||
- book-outline-tmpl.yaml
|
||||
checklists:
|
||||
- learning-objectives-checklist.md
|
||||
data:
|
||||
- bmad-kb.md
|
||||
- learning-frameworks.md
|
||||
```
|
||||
|
||||
**Dependency Resolution**:
|
||||
- Dependencies are loaded on-demand when agent executes command
|
||||
- Recursive resolution (templates can reference tasks, etc.)
|
||||
- Path mapping: `{root}/{type}/{name}` (e.g., `{root}/tasks/create-doc.md`)
|
||||
|
||||
### Build System
|
||||
|
||||
The Technical Writing Pack integrates with BMad's build system:
|
||||
|
||||
**Build Process**:
|
||||
1. Reads agent/workflow/template definitions
|
||||
2. Resolves dependencies recursively
|
||||
3. Bundles content into `.txt` files for web UI
|
||||
4. Outputs to `dist/` directory
|
||||
|
||||
**Build Commands**:
|
||||
```bash
|
||||
npm run build # Build everything
|
||||
npm run build:agents # Only agent bundles
|
||||
npm run build:teams # Only team bundles
|
||||
npm run validate # Validate all configs
|
||||
```
|
||||
|
||||
### Web UI vs IDE Usage
|
||||
|
||||
The Technical Writing Pack works in two environments:
|
||||
|
||||
#### Web UI (Gemini, ChatGPT, Claude)
|
||||
**Use For**: Planning phase (book outline, learning objectives, chapter structure)
|
||||
|
||||
**How It Works**:
|
||||
1. Build system creates bundled `.txt` files with all dependencies
|
||||
2. User uploads bundle to chat interface
|
||||
3. Agent activates with full context
|
||||
4. User executes planning workflows
|
||||
5. Downloads deliverables (book outline, chapter plans)
|
||||
|
||||
**Advantages**:
|
||||
- Rich context (entire knowledge base available)
|
||||
- No token limits during planning
|
||||
- Easy to share and collaborate
|
||||
|
||||
**Files**:
|
||||
- `dist/agents/instructional-designer.txt` (bundled agent)
|
||||
- `dist/teams/planning-team.txt` (multi-agent bundle)
|
||||
|
||||
#### IDE (Cursor, VS Code, Claude Code)
|
||||
**Use For**: Development phase (writing content, creating code, reviewing)
|
||||
|
||||
**How It Works**:
|
||||
1. Agents load individual `.md` files from expansion pack
|
||||
2. Dependencies resolved on-demand from project structure
|
||||
3. Agent works directly with project files
|
||||
4. Changes committed to version control
|
||||
|
||||
**Advantages**:
|
||||
- Direct file editing
|
||||
- Code creation and testing
|
||||
- Git integration
|
||||
- Efficient for development
|
||||
|
||||
**Activation**:
|
||||
```
|
||||
/bmad-tw:tutorial-architect
|
||||
/bmad-tw:code-curator
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agents
|
||||
|
||||
The Technical Writing Pack provides 13 specialized agents organized in categories:
|
||||
|
||||
### Core Planning Agents
|
||||
- **Instructional Designer** 🎓 - Learning architecture, pedagogical structure, Bloom's taxonomy
|
||||
- **Tutorial Architect** 📝 - Hands-on tutorials, step-by-step guides, exercises
|
||||
- **Code Curator** 💻 - Code examples, testing, version management
|
||||
|
||||
### Core Review Agents
|
||||
- **Technical Reviewer** 🔍 - Technical accuracy, security, best practices
|
||||
- **Technical Editor** ✍️ - Clarity, style, publisher compliance, accessibility
|
||||
|
||||
### Core Publishing Agent
|
||||
- **Book Publisher** 📦 - Publication preparation, manuscript packaging, submissions
|
||||
|
||||
### Specialist Agents
|
||||
- **API Documenter** 📚 - API references, technical specs, glossaries
|
||||
- **Screenshot Specialist** 📸 - Diagrams, screenshots, visual documentation
|
||||
- **Exercise Creator** 🏋️ - Practice problems, assessments, solutions
|
||||
|
||||
### Brownfield Agent
|
||||
- **Book Analyst** 📖 - Existing book analysis, revision planning, edition updates
|
||||
|
||||
### Optional Agents (Advanced)
|
||||
- **Learning Path Designer** 🗺️ - Complex prerequisite mapping, skill progression
|
||||
- **Sample Code Maintainer** 🔧 - Repository management, CI/CD, dependency updates
|
||||
- **Version Manager** 🔢 - Multi-version compatibility, platform-specific code
|
||||
|
||||
**→ See [Agent Reference Guide](agent-reference.md) for complete documentation**
|
||||
|
||||
---
|
||||
|
||||
## Workflows
|
||||
|
||||
The pack provides 15 workflows organized by phase:
|
||||
|
||||
### Planning (1)
|
||||
- `book-planning-workflow` - Complete book planning from concept to approved outline
|
||||
|
||||
### Development (6)
|
||||
- `chapter-development-workflow` - Complete chapter creation
|
||||
- `section-planning-workflow` - Break chapter into sections
|
||||
- `section-development-workflow` - Write individual sections
|
||||
- `chapter-assembly-workflow` - Merge sections into chapter
|
||||
- `tutorial-creation-workflow` - Hands-on tutorial development
|
||||
- `code-example-workflow` - Code example creation and testing
|
||||
|
||||
### Review (2)
|
||||
- `technical-review-workflow` - Technical accuracy verification
|
||||
- `incorporate-review-feedback-workflow` - Apply reviewer feedback
|
||||
|
||||
### Publishing (4)
|
||||
- `packtpub-submission-workflow` - PacktPub submission preparation
|
||||
- `oreilly-submission-workflow` - O'Reilly standards compliance
|
||||
- `manning-meap-workflow` - Manning MEAP release
|
||||
- `self-publishing-workflow` - Leanpub/KDP/Gumroad preparation
|
||||
|
||||
### Brownfield (2)
|
||||
- `book-edition-update-workflow` - 2nd/3rd edition revisions
|
||||
- `add-chapter-to-existing-book-workflow` - Add chapters to existing books
|
||||
|
||||
**→ See [Workflow Guide](workflow-guide.md) for complete documentation and decision tree**
|
||||
|
||||
---
|
||||
|
||||
## Templates
|
||||
|
||||
18 professional templates organized by category:
|
||||
|
||||
### Planning (3)
|
||||
- `book-outline-tmpl` - Complete book structure
|
||||
- `book-proposal-tmpl` - Publisher proposal
|
||||
- `chapter-outline-tmpl` - Chapter structure with sections
|
||||
|
||||
### Chapter Content (5)
|
||||
- `section-plan-tmpl` - Individual section plan
|
||||
- `chapter-draft-tmpl` - Chapter content
|
||||
- `introduction-tmpl` - Chapter introduction
|
||||
- `preface-tmpl` - Book preface
|
||||
- `appendix-tmpl` - Technical appendix
|
||||
|
||||
### Code (2)
|
||||
- `code-example-tmpl` - Code examples with tests
|
||||
- `api-reference-tmpl` - API documentation
|
||||
|
||||
### Learning (2)
|
||||
- `learning-objectives-tmpl` - Learning outcomes
|
||||
- `exercise-set-tmpl` - Practice exercises
|
||||
|
||||
### Tutorial (1)
|
||||
- `tutorial-section-tmpl` - Hands-on tutorial
|
||||
|
||||
### Review (2)
|
||||
- `technical-review-report-tmpl` - Review findings
|
||||
- `revision-plan-tmpl` - Edition update plan
|
||||
|
||||
### Visual (1)
|
||||
- `diagram-spec-tmpl` - Diagram specifications
|
||||
|
||||
### Documentation (2)
|
||||
- `glossary-entry-tmpl` - Glossary terms
|
||||
- `book-analysis-report-tmpl` - Existing book analysis
|
||||
|
||||
**→ See [Template Gallery](template-gallery.md) for examples and usage**
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
33 tasks organized by phase:
|
||||
|
||||
### Planning (6)
|
||||
- `design-book-outline` - Create book structure
|
||||
- `create-learning-objectives` - Define learning outcomes
|
||||
- `create-chapter-outline` - Plan chapter structure
|
||||
- `design-learning-path` - Map skill progression
|
||||
- `create-preface` - Write book introduction
|
||||
- `build-glossary` - Create terminology reference
|
||||
|
||||
### Chapter Development (8)
|
||||
- `write-chapter-draft` - Write chapter content
|
||||
- `write-introduction` - Create chapter intro
|
||||
- `write-summary` - Write chapter summary
|
||||
- `develop-tutorial` - Create hands-on tutorial
|
||||
- `design-exercises` - Create practice problems
|
||||
- `create-solutions` - Write exercise solutions
|
||||
- `design-diagram-set` - Plan visual documentation
|
||||
- `validate-cross-references` - Check internal links
|
||||
|
||||
### Code Management (5)
|
||||
- `create-code-example` - Write code samples
|
||||
- `test-code-examples` - Verify code works
|
||||
- `setup-code-repository` - Initialize Git repo
|
||||
- `version-matrix-check` - Test multi-version compatibility
|
||||
- `generate-api-docs` - Create API reference
|
||||
|
||||
### Review & Editing (4)
|
||||
- `technical-review-chapter` - Verify accuracy
|
||||
- `copy-edit-chapter` - Polish writing
|
||||
- `create-diagram-spec` - Design diagrams
|
||||
- `take-screenshots` - Capture visuals
|
||||
|
||||
### Publishing (7)
|
||||
- `package-for-publisher` - Prepare submission
|
||||
- `prepare-meap-chapter` - Manning beta release
|
||||
- `self-publish-prep` - Self-publishing preparation
|
||||
- `create-appendix` - Write appendix
|
||||
- `create-index-entries` - Generate index
|
||||
- `incorporate-reviewer-feedback` - Apply feedback
|
||||
- `plan-book-revision` - Plan edition update
|
||||
|
||||
### Documentation (3)
|
||||
- `build-glossary` - Create glossary
|
||||
- `create-index-entries` - Build index
|
||||
- `validate-cross-references` - Verify links
|
||||
|
||||
**→ See [Task Reference](task-reference.md) for complete documentation**
|
||||
|
||||
---
|
||||
|
||||
## Checklists
|
||||
|
||||
31 checklists organized by phase:
|
||||
|
||||
### Planning (2)
|
||||
- `learning-objectives-checklist` - Validate learning outcomes
|
||||
- `prerequisite-clarity-checklist` - Verify prerequisites
|
||||
|
||||
### Drafting (5)
|
||||
- `chapter-completeness-checklist` - Ensure chapter complete
|
||||
- `tutorial-effectiveness-checklist` - Validate tutorials
|
||||
- `exercise-difficulty-checklist` - Verify exercise quality
|
||||
- `readability-checklist` - Check clarity
|
||||
- `inclusive-language-checklist` - Ensure inclusivity
|
||||
|
||||
### Code Quality (5)
|
||||
- `code-quality-checklist` - Verify code standards
|
||||
- `code-testing-checklist` - Ensure tests pass
|
||||
- `version-compatibility-checklist` - Check versions
|
||||
- `cross-platform-checklist` - Test platforms
|
||||
- `repository-quality-checklist` - Validate repo
|
||||
|
||||
### Review (4)
|
||||
- `technical-accuracy-checklist` - Verify correctness
|
||||
- `security-best-practices-checklist` - Check security
|
||||
- `performance-considerations-checklist` - Review performance
|
||||
- `citation-accuracy-checklist` - Validate citations
|
||||
|
||||
### Publishing (7)
|
||||
- `packtpub-submission-checklist` - PacktPub requirements
|
||||
- `oreilly-format-checklist` - O'Reilly standards
|
||||
- `manning-meap-checklist` - Manning MEAP requirements
|
||||
- `meap-readiness-checklist` - Beta release readiness
|
||||
- `self-publishing-standards-checklist` - Self-pub standards
|
||||
- `accessibility-checklist` - WCAG compliance
|
||||
- `book-proposal-checklist` - Proposal completeness
|
||||
|
||||
### Final QA (8)
|
||||
- `final-manuscript-checklist` - Complete manuscript review
|
||||
- `index-completeness-checklist` - Verify index
|
||||
- `diagram-clarity-checklist` - Check diagrams
|
||||
- `screenshot-quality-checklist` - Verify screenshots
|
||||
- `glossary-accuracy-checklist` - Check glossary
|
||||
- Plus 3 more for brownfield scenarios
|
||||
|
||||
**→ See [Checklist Reference](checklist-reference.md) for complete documentation**
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
Ready to write your technical book? Here's what to do next:
|
||||
|
||||
### 1. Quick Start (5 Minutes)
|
||||
Read the [Quick Reference Card](quick-reference.md) for a one-page overview of most common workflows, agents, and commands.
|
||||
|
||||
### 2. Hands-On Tutorial (1-2 Hours)
|
||||
Follow the [Getting Started Tutorial](getting-started.md) to write your first chapter using the "Python Data Structures Handbook" example. You'll learn:
|
||||
- How to plan a book
|
||||
- How to outline a chapter
|
||||
- How to write a section
|
||||
- How to review and polish content
|
||||
- How to prepare for publishing
|
||||
|
||||
### 3. Deep Dive (Optional)
|
||||
Explore detailed reference documentation:
|
||||
- [Process Flows](process-flows.md) - Visual diagrams of all workflows
|
||||
- [Agent Reference](agent-reference.md) - Complete agent documentation
|
||||
- [Workflow Guide](workflow-guide.md) - All workflows with decision tree
|
||||
- [Template Gallery](template-gallery.md) - All templates with examples
|
||||
|
||||
### 4. Get Support
|
||||
- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions
|
||||
- [FAQ](faq.md) - Frequently asked questions
|
||||
- [Discord Community](https://discord.gg/gk8jAdXWmj) - Ask questions and share
|
||||
- [GitHub Issues](https://github.com/bmadcode/bmad-method/issues) - Report bugs
|
||||
|
||||
### Recommended Learning Path
|
||||
|
||||
**Beginners**:
|
||||
1. Quick Reference (5 min)
|
||||
2. Getting Started Tutorial (1-2 hours)
|
||||
3. Start writing your first chapter!
|
||||
|
||||
**Intermediate Users**:
|
||||
1. Process Flows (understand orchestration)
|
||||
2. Agent Reference (know all agent capabilities)
|
||||
3. Workflow Guide (choose right workflows)
|
||||
|
||||
**Advanced Users**:
|
||||
1. Integration Guide (multi-expansion usage)
|
||||
2. Task Reference (customize workflows)
|
||||
3. Template Gallery (create custom templates)
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
- 📖 **Complete tutorial**: [Getting Started Guide](getting-started.md)
|
||||
- 📋 **Quick reference**: [Quick Reference Card](quick-reference.md)
|
||||
- ❓ **Common issues**: [Troubleshooting Guide](troubleshooting.md)
|
||||
- 💬 **Ask community**: [Discord](https://discord.gg/gk8jAdXWmj)
|
||||
- 🐛 **Report bugs**: [GitHub Issues](https://github.com/bmadcode/bmad-method/issues)
|
||||
|
||||
**Ready to write your book? → [Start Tutorial](getting-started.md)**
|
||||
|
||||
---
|
||||
|
||||
*Technical Writing Expansion Pack v1.1.0*
|
||||
*Part of BMad-Method™ - The Universal AI Agent Framework*
|
||||
Loading…
Reference in New Issue