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

BMad Technical Writing Expansion Pack

Transform your AI into a complete technical book writing studio with specialized agents for technical authors, trainers, and documentation specialists.

📚 Overview

The Technical Writing Expansion Pack extends BMad-Method with a comprehensive suite of tools for creating high-quality technical books, tutorials, and instructional content. Whether you're writing for PacktPub, O'Reilly, Manning, or self-publishing, this pack provides structured AI assistance throughout your technical writing process.

Key Features

• 🤖 6 Specialized Agents - Complete writing team from planning to publication
• 📝 10 Core Tasks - Full chapter development workflow
• 📋 15 Quality Checklists - Technical accuracy, security, performance, publisher compliance, accessibility
• 🎯 10 Professional Templates - Book planning, chapter development, section planning, review, and publishing
• 📚 6 Knowledge Bases - Comprehensive publisher guidelines and technical writing standards
• 🔄 8 Core Workflows - Section-driven development with complete orchestration from book planning to technical review

✍️ Included Agents

Planning & Design Team (Sprint 1)

1. Instructional Designer 🎓 - Learning objectives, pedagogical structure, and instructional scaffolding
2. Tutorial Architect 🏗️ - Hands-on tutorial design, exercise creation, and progressive learning paths
3. Code Curator 🔧 - Code example development, testing, version management, and quality assurance

Review & Publishing Team (Sprint 2)

4. Technical Reviewer 🔍 - Technical accuracy verification, security audits, best practices validation
5. Technical Editor ✍️ - Clarity improvement, style consistency, publisher formatting, accessibility
6. Book Publisher 📦 - Publication preparation, manuscript packaging, publisher-specific formatting

🚀 Installation

Via BMad Installer

npx bmad-method install
# Select "Technical Book Writing Studio" from the expansion packs list

Manual Installation

1. Clone or download this expansion pack
2. Copy to your BMad Method installation:

   cp -r bmad-technical-writing/* ~/bmad-method/expansion-packs/bmad-technical-writing/
   

3. Run the BMad installer to register the pack

💡 Usage

Quick Start

# Activate individual agents in your IDE
/bmad-tw:instructional-designer
/bmad-tw:tutorial-architect
/bmad-tw:code-curator
/bmad-tw:technical-reviewer
/bmad-tw:technical-editor
/bmad-tw:book-publisher

Core Workflows (Sprint 2, 2.5, 2.6)

Book Planning Workflow (Sprint 2.5) - Complete book planning from concept to approved outline:

1. Book Publisher drafts comprehensive book proposal
2. Instructional Designer creates detailed book outline
3. Instructional Designer validates learning progression
4. Technical Editor reviews outline for clarity
5. Book Publisher verifies publisher requirements

Chapter Development Workflow v2.0 (Sprint 2, refactored Sprint 2.6) - Complete chapter creation from outline to publisher-ready:

Section-Driven Approach (NEW in v2.0):

1. Tutorial Architect creates chapter outline
2. Tutorial Architect + Instructional Designer plan sections (section-planning-workflow)
3. For each section: Code Curator + Tutorial Architect + Technical Reviewer develop section (section-development-workflow)
4. Tutorial Architect + Technical Editor + Technical Reviewer assemble chapter (chapter-assembly-workflow)
5. Final validation and publication readiness

Traditional Approach (Original, still supported):

1. Tutorial Architect creates chapter outline
2. Code Curator develops and tests all code examples
3. Tutorial Architect writes complete chapter draft
4. Technical Reviewer performs comprehensive technical review
5. Tutorial Architect revises based on review feedback
6. Technical Editor performs professional copy editing
7. Tutorial Architect finalizes chapter for publication

Section Planning Workflow (Sprint 2.6) - Break chapter into deliverable sections (BMad story analog):

1. Tutorial Architect analyzes chapter outline
2. Tutorial Architect identifies section boundaries (5-8 sections)
3. Tutorial Architect creates section plans with acceptance criteria
4. Instructional Designer validates learning flow
5. Tutorial Architect finalizes section list

Section Development Workflow (Sprint 2.6) - Write one section (2-5 pages):

1. Code Curator develops section code examples
2. Code Curator tests all code
3. Tutorial Architect writes section content
4. Technical Reviewer performs focused section review
5. Tutorial Architect revises section
6. Tutorial Architect finalizes section (DONE)

Chapter Assembly Workflow (Sprint 2.6) - Integrate completed sections (BMad Sprint Review analog):

1. Tutorial Architect merges all completed sections
2. Tutorial Architect improves transitions
3. Instructional Designer validates learning flow
4. Technical Reviewer performs full chapter review
5. Tutorial Architect revises based on feedback
6. Technical Editor performs copy editing
7. Tutorial Architect finalizes chapter for publication

Tutorial Creation Workflow (Sprint 2) - Build effective hands-on tutorials:

1. Instructional Designer designs learning path
2. Tutorial Architect creates step-by-step structure
3. Code Curator develops and tests tutorial code
4. Tutorial Architect writes complete tutorial
5. Code Curator tests end-to-end
6. Tutorial Architect revises based on testing
7. Instructional Designer validates learning effectiveness

Code Example Workflow (Sprint 2.5) - Develop, test, and document code examples:

1. Code Curator develops code example
2. Code Curator tests on all target platforms
3. Code Curator verifies code quality
4. Code Curator performs security review
5. Code Curator adds comprehensive documentation

Technical Review Workflow (Sprint 2.5) - Comprehensive expert review of chapter:

1. Technical Reviewer verifies technical accuracy
2. Code Curator reviews all code examples
3. Technical Reviewer validates best practices
4. Technical Reviewer compiles comprehensive report

Common Use Cases

• Book Planning - Create comprehensive book outlines with learning objectives
• Chapter Development - Full workflow from outline to publication-ready manuscript
• Code Example Creation - Develop, test, and document working code examples
• Technical Review - Verify accuracy, security, and best practices
• Editorial Polish - Ensure clarity, consistency, and publisher compliance
• Quality Assurance - 15 checklists covering all aspects of technical writing quality

📋 Key Components

Templates (10 Total)

Sprint 1 (Planning):

• book-outline-tmpl.yaml - Complete book structure with learning path
• chapter-outline-tmpl.yaml - Individual chapter planning with exercises
• code-example-tmpl.yaml - Code examples with explanations and testing

Sprint 2 (Writing & Publishing):

• chapter-draft-tmpl.yaml - Complete chapter manuscript structure
• technical-review-report-tmpl.yaml - Review findings and recommendations
• tutorial-section-tmpl.yaml - Step-by-step tutorial structure
• exercise-set-tmpl.yaml - Practice exercises with solutions
• book-proposal-tmpl.yaml - Publisher proposal document
• introduction-tmpl.yaml - Chapter introduction structure

Sprint 2.6 (Section-Driven Development):

• section-plan-tmpl.yaml - Section plan with acceptance criteria (BMad story analog)

Tasks (10 Total)

Sprint 1 (Planning):

• design-book-outline.md - Create publisher-aligned book structures
• create-code-example.md - Develop tested, documented code examples
• test-code-examples.md - Automated testing workflow for all examples
• create-learning-objectives.md - Define measurable learning outcomes
• create-chapter-outline.md - Plan chapter structure and content

Sprint 2 (Writing & Review):

• write-chapter-draft.md - Complete chapter manuscript writing workflow
• technical-review-chapter.md - Comprehensive chapter review workflow
• copy-edit-chapter.md - Editorial polish workflow
• develop-tutorial.md - Hands-on tutorial creation workflow
• design-exercises.md - Exercise creation workflow

Checklists (15 Total)

Sprint 1 (Quality Foundations):

• Learning objectives validation
• Code quality verification
• Code testing requirements
• Tutorial effectiveness
• Chapter completeness
• Exercise difficulty assessment
• Prerequisite clarity
• Version compatibility

Sprint 2 (Review & Publishing):

• Technical accuracy checklist
• Security best practices checklist
• Performance considerations checklist
• PacktPub submission checklist
• O'Reilly format checklist
• Manning MEAP checklist
• Accessibility checklist

Workflows (8 Core Workflows)

Sprint 2:

• chapter-development-workflow.yaml - Complete chapter creation workflow (v2.0 - refactored Sprint 2.6)
• tutorial-creation-workflow.yaml - Tutorial development workflow

Sprint 2.5:

• book-planning-workflow.yaml - Book planning from concept to approved outline
• code-example-workflow.yaml - Code example development and testing
• technical-review-workflow.yaml - Comprehensive technical review

Sprint 2.6 (Section-Driven Development):

• section-planning-workflow.yaml - Break chapter into sections (BMad epic → stories analog)
• section-development-workflow.yaml - Write one section (BMad story development analog)
• chapter-assembly-workflow.yaml - Merge sections into chapter (BMad sprint review analog)

Knowledge Bases (6 Total)

• bmad-kb.md - Core technical writing methodology
• book-structures.md - PacktPub, O'Reilly, Manning formats
• learning-frameworks.md - Bloom's Taxonomy, scaffolding principles
• code-style-guides.md - Python, JavaScript, Java standards (COMPLETE)
• publisher-guidelines.md - Publisher-specific requirements (EXPANDED in Sprint 2)
• technical-writing-standards.md - Writing standards (COMPLETE in Sprint 2)

🎯 Use Cases

Technical Book Writing

• Plan complete book structure with learning objectives
• Design hands-on tutorials and exercises
• Create and test code examples across versions
• Validate pedagogical effectiveness

Course Material Development

• Structure learning paths for technical courses
• Create progressive tutorial sequences
• Develop practice exercises with solutions
• Ensure prerequisite clarity

Documentation Writing

• Design tutorial-based documentation
• Create working code examples
• Structure content for different learning styles
• Validate instructional effectiveness

Book Updates (Brownfield)

• Update existing books for new framework versions
• Add new chapters to existing content
• Refresh code examples for current standards
• Incorporate technical reviewer feedback

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Follow BMad Method conventions
4. Submit a PR with clear description

📄 License

This expansion pack follows the same license as BMad Method core.

🙏 Credits

Created by Wes for the BMad Method community.

Special thanks to Brian (BMad) for creating the BMad Method framework.

---

Version: 0.2.6 (Sprint 2.6 - Section-Driven Development) Compatible with: BMad Method v4.0+ Last Updated: 2024

✅ Sprint Status

Sprint 1 (Complete): Planning and design foundation

• ✅ 3 planning agents (Instructional Designer, Tutorial Architect, Code Curator)
• ✅ 5 core tasks for book and chapter planning
• ✅ 8 quality checklists
• ✅ 3 templates for planning
• ✅ 6 knowledge bases (initial versions)

Sprint 2 (Complete): Review, workflows, and quality assurance

• ✅ 3 review agents (Technical Reviewer, Technical Editor, Book Publisher)
• ✅ 5 additional tasks for writing and review
• ✅ 7 additional checklists (technical, security, performance, publisher, accessibility)
• ✅ 6 additional templates for writing and publishing
• ✅ 2 core workflows (chapter development, tutorial creation)
• ✅ Expanded knowledge bases (publisher guidelines, writing standards)

Sprint 2.5 (Complete): Workflow orchestration completion

• ✅ 3 additional workflows: Book Planning Workflow, Code Example Workflow, Technical Review Workflow
• ✅ Total: 5 core workflows for complete book development
• ✅ Version bumped to 0.2.5

Sprint 2.6 (Complete): Section-driven development (BMad story analog)

• ✅ 3 section-level workflows: Section Planning, Section Development, Chapter Assembly
• ✅ 1 new template: Section Plan Template (section acceptance criteria)
• ✅ Refactored Chapter Development Workflow v2.0 (orchestrates section workflows)
• ✅ Total: 8 core workflows, 10 templates
• ✅ Section-driven approach enables incremental chapter writing (2-5 pages per section)
• ✅ Perfect analog to BMad's story-driven development workflow
• ✅ Parallel section development supported
• ✅ Backward compatible: Traditional full-chapter approach still supported
• ✅ Version bumped to 0.2.6

📚 Section-Driven Development Approach (NEW in Sprint 2.6)

The section-driven approach mirrors BMad's story-driven development workflow, enabling incremental chapter writing:

Key Concepts:

• Section = Story analog: Each section is a 2-5 page deliverable unit with clear acceptance criteria
• Incremental progress: Track "Chapter 3: 5 of 8 sections complete" like story completion
• Parallel development: Multiple sections can be developed simultaneously if dependencies allow
• Work-in-progress reviews: Review sections as they're completed, not waiting for full chapter
• Story-driven iteration: Write → Review → Polish cycle at section level

Typical Chapter Breakdown:

• 20-page chapter = 5-8 sections
• Small section: 2-3 pages, 1 concept, 1 code example (3 story points)
• Medium section: 3-4 pages, 1-2 concepts, 2 code examples (5 story points)
• Large section: 4-5 pages, 2-3 concepts, 2-3 code examples (8 story points)

Workflow Mapping:

BMad Software Dev	Book Writing (Section-Driven)
PRD Creation	book-planning-workflow → book outline
Architecture	chapter-planning → chapter outline
Epic Breakdown	section-planning-workflow → section list
Story Development	section-development-workflow → completed section
Sprint Review	chapter-assembly-workflow → integrated chapter
Release	publisher-submission → published chapter

When to Use Section-Driven:

• Chapters 15+ pages (too large for single sitting)
• Want incremental progress tracking
• Need parallel development capability
• Prefer iterative story-driven approach
• Want to review work before full chapter complete

When to Use Traditional:

• Short chapters (<10-12 pages)
• Simple reference sections
• Author prefers writing full chapter at once
• Chapter already partially written

🚧 Roadmap

Sprint 3 (Planned):

• API Documenter agent
• Screenshot Specialist agent
• Additional publisher-specific agents
• Video tutorial support
• Internationalization support