272 lines
6.9 KiB
Markdown
272 lines
6.9 KiB
Markdown
# 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
|