BMAD-METHOD/expansion-packs/bmad-technical-writing/data/bmad-kb.md

BMad Technical Writing Knowledge Base

Overview

BMad Technical Writing transforms you into a "Book Director" - orchestrating specialized AI agents through the technical book creation process. This expansion pack provides structured workflows for creating high-quality technical books with code examples, tutorials, and progressive learning paths.

When to Use BMad Technical Writing

Use this expansion pack for:

• Writing technical books (PacktPub, O'Reilly, Manning, self-publish)
• Creating comprehensive tutorials and course materials
• Developing technical documentation with code examples
• Updating existing technical books (2nd/3rd editions, version updates)
• Incorporating technical reviewer feedback
• Managing code example testing and maintenance

The Core Method

1. You Author, AI Supports

You provide:

• Technical expertise and domain knowledge
• Teaching insights and pedagogical decisions
• Code examples and real-world experience

Agents handle:

• Structure and organization
• Consistency and quality assurance
• Learning progression validation
• Publisher compliance checking

2. Specialized Agents

Each agent masters one aspect:

• Instructional Designer: Learning architecture, objectives, scaffolding
• Code Curator: Example development, testing, version management
• Tutorial Architect: Step-by-step instruction, hands-on learning
• Technical Reviewer: Accuracy verification, best practices (Sprint 2)
• Technical Editor: Polish, clarity, consistency (Sprint 2)
• Book Publisher: Submission packaging, formatting (Sprint 2)

3. Quality-First Approach

Multiple review passes ensure:

• Technical accuracy and current best practices
• Working code examples tested across versions
• Clear learning progression with proper scaffolding
• Publisher compliance and formatting
• Pedagogically sound instruction

Four-Phase Approach

Phase 1: Planning (Web UI - Gemini/ChatGPT)

Agents: Instructional Designer

Activities:

• Design book outline with learning path
• Define book-level and chapter-level learning objectives
• Map prerequisites and dependencies
• Structure parts and chapters
• Plan code repository

Outputs:

• Complete book outline
• Learning objectives matrix
• Chapter dependency map

Phase 2: Development (IDE - Cursor/VS Code/Claude Code)

Agents: Tutorial Architect, Code Curator

Activities:

• Create detailed chapter outlines
• Write chapter content with tutorials
• Develop code examples
• Test code across versions/platforms
• Create exercises and challenges

Outputs:

• Chapter drafts
• Working code examples
• Exercise sets
• Test results

Phase 3: Review (IDE or Web UI)

Agents: Technical Reviewer, Technical Editor (Sprint 2)

Activities:

• Technical accuracy verification
• Code quality review
• Editorial pass for clarity
• Consistency checking
• Publisher guideline compliance

Outputs:

• Technical review reports
• Edited chapters
• Code improvements

Phase 4: Publishing (IDE)

Agents: Book Publisher (Sprint 2)

Activities:

• Format for target publisher
• Package submission materials
• Create index and glossary
• Final quality assurance

Outputs:

• Publisher-ready manuscript
• Submission package
• Companion code repository

Agent Specializations Summary

Instructional Designer 🎓

• Creates book and chapter outlines
• Defines learning objectives using Bloom's Taxonomy
• Designs learning paths with proper scaffolding
• Maps prerequisites and dependencies
• Ensures pedagogical soundness

Tutorial Architect 📝

• Designs hands-on tutorials
• Creates step-by-step instructions
• Develops exercises and challenges
• Ensures reproducibility
• Adds troubleshooting guidance

Code Curator 💻

• Develops working code examples
• Tests code across versions and platforms
• Manages version compatibility
• Ensures code quality and best practices
• Creates automated test suites

Best Practices

Learning Progression

• Start simple, add complexity gradually
• Introduce concepts before using them
• Provide practice before advancing
• Use Bloom's Taxonomy progression (Remember→Understand→Apply→Analyze→Evaluate→Create)
• Validate prerequisites are clear

Code Examples

• Every example must be tested and working
• Follow language-specific style guides
• Include inline comments explaining WHY, not WHAT
• Document setup and dependencies precisely
• Test across specified versions and platforms
• Provide troubleshooting for common issues

Tutorial Design

• Use clear, actionable steps
• Document expected results at each stage
• Provide hands-on practice opportunities
• Include troubleshooting guidance
• Ensure reproducibility

Chapter Structure

• Introduction with real-world motivation
• Learning objectives stated upfront
• Concepts explained before application
• Tutorials reinforce concepts
• Exercises provide practice
• Summary recaps key points

Quality Assurance

• Use checklists to validate quality
• Test all code examples before publishing
• Verify prerequisites are explicit
• Ensure learning objectives are measurable
• Check alignment with publisher guidelines

Publisher-Specific Considerations

PacktPub

• Hands-on, project-based approach
• Practical tutorials throughout
• Clear learning outcomes per chapter
• Code-heavy with examples

O'Reilly

• Learning path structure
• Exercises after each concept
• Real-world examples
• Theory balanced with practice

Manning

• Deep tutorial style
• Progressive build approach
• Iterative improvements
• Comprehensive coverage

Self-Publishing

• Flexible structure
• Follow general best practices
• Consider target platform (Leanpub, KDP, etc.)
• Maintain high quality standards

Bloom's Taxonomy Reference

Use action verbs appropriate to learning level:

• Remember: Define, List, Name, Identify, Describe
• Understand: Explain, Summarize, Interpret, Compare
• Apply: Implement, Execute, Use, Build, Demonstrate
• Analyze: Analyze, Debug, Troubleshoot, Examine
• Evaluate: Evaluate, Assess, Critique, Optimize
• Create: Design, Develop, Architect, Construct

Version Management

For technical books:

• Specify exact versions in prerequisites (e.g., "Python 3.11+")
• Test code on all supported versions
• Document version-specific behaviors
• Create version compatibility matrix
• Plan for updates when new versions release

Brownfield Support

BMad Technical Writing fully supports updating existing books:

• Add new chapters to existing content
• Update code examples for new framework versions
• Refresh outdated examples
• Incorporate technical reviewer feedback
• Maintain consistency with existing content
• Update for new publisher requirements

Success Metrics

A successful technical book should:

• Have clear, measurable learning objectives
• Include working code examples (100% tested)
• Provide hands-on tutorials and exercises
• Follow proper learning progression
• Meet publisher guidelines
• Enable readers to achieve stated objectives