# 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