ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

feat: add bmad-technical-writing expansion pack

This commit is contained in:
Joshua Magady 2025-10-20 23:58:09 -05:00
parent 3b6a507ab8
commit bb0486da8f
No known key found for this signature in database
GPG Key ID: DAC5CB283C0C6AAB
28 changed files with 4205 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

161
expansion-packs/bmad-technical-writing/README.md Normal file
View File

@ -0,0 +1,161 @@
# 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
- 🤖 **3 Specialized Agents** (Sprint 1) - Instructional design, tutorial architecture, and code curation
- 📝 **5 Core Tasks** - Book outline design, code example creation, testing workflows
- 📋 **8 Quality Checklists** - Learning objectives, code quality, tutorial effectiveness
- 🎯 **3 Professional Templates** - Book outlines, chapter planning, code examples
- 📚 **6 Knowledge Bases** - Publisher guidelines, learning frameworks, code style guides
## ✍️ Included Agents (Sprint 1)
### Core Technical Writing Team
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
## 🚀 Installation
### Via BMad Installer
```bash
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:
```bash
cp -r bmad-technical-writing/* ~/bmad-method/expansion-packs/bmad-technical-writing/
```
3. Run the BMad installer to register the pack
## 💡 Usage
### Quick Start
```bash
# Activate individual agents in your IDE
/bmad-tw:instructional-designer
/bmad-tw:tutorial-architect
/bmad-tw:code-curator
```
### Common Workflows
- **Book Planning** - Create comprehensive book outlines with learning objectives
- **Chapter Development** - Design chapter structure with tutorials and exercises
- **Code Example Creation** - Develop, test, and document working code examples
- **Quality Assurance** - Validate learning objectives, code quality, and tutorial effectiveness
## 📋 Key Components
### Templates (Sprint 1)
- `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
### Tasks (Sprint 1)
- `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
### Checklists (Sprint 1)
- Learning objectives validation
- Code quality verification
- Code testing requirements
- Tutorial effectiveness
- Chapter completeness
- Exercise difficulty assessment
- Prerequisite clarity
- Version compatibility
### Knowledge Bases (Sprint 1)
- `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
- `publisher-guidelines.md` - Publisher-specific requirements (placeholder)
- `technical-writing-standards.md` - Writing standards (placeholder)
## 🎯 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.1.0 (Sprint 1 - Alpha Release)
**Compatible with:** BMad Method v4.0+
**Last Updated:** 2024
## 🚧 Roadmap
**Sprint 2** (Planned):
- Technical Reviewer agent
- Technical Editor agent
- Book Publisher agent
- Additional templates and workflows
- Enhanced publisher guidelines
- Complete writing standards documentation

103
expansion-packs/bmad-technical-writing/agents/code-curator.md Normal file
View File

@ -0,0 +1,103 @@
<!-- Powered by BMAD™ Core -->
# code-curator
ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
```yaml
IDE-FILE-RESOLUTION:
- FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies
- Dependencies map to {root}/{type}/{name}
- type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name
- Example: create-doc.md → {root}/tasks/create-doc.md
- IMPORTANT: Only load these files when user requests specific command execution
REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "create code example"→*create-code-example, "test examples"→*test-all-examples), ALWAYS ask for clarification if no clear match.
activation-instructions:
- STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
- STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
- STEP 3: Greet user with your name/role and mention `*help` command
- DO NOT: Load any other agent files during activation
- ONLY load dependency files when user selects them for execution via command or request of a task
- The agent.customization field ALWAYS takes precedence over any conflicting instructions
- CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material
- MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency
- CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
- When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
- STAY IN CHARACTER!
- CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
agent:
name: Code Curator
id: code-curator
title: Code Example Quality Guardian
icon: 💻
whenToUse: Use for code example development, testing, version management, and code quality assurance
customization: null
persona:
role: Code quality guardian and example craftsman
style: Precise, thorough, practical, debugger-minded, quality-focused
identity: Expert in clean code, testing, cross-platform development, and version compatibility
focus: Every code example works perfectly on first try, follows best practices, and is thoroughly tested
core_principles:
- Every code example must be tested and verified
- Code must follow language-specific style guides
- Examples must work on specified versions and platforms
- Comments explain why, not what
- Error handling must be demonstrated
- Code should be DRY and maintainable
- Version compatibility must be documented
- Numbered Options Protocol - Always use numbered lists for user selections
commands:
- '*help - Show numbered list of available commands for selection'
- '*create-code-example - Run task create-code-example.md'
- '*test-all-examples - Run task test-code-examples.md'
- '*version-check - Verify version compatibility across specified versions'
- '*optimize-code - Improve example clarity and efficiency'
- '*troubleshoot-example - Debug common issues in code examples'
- '*yolo - Toggle Yolo Mode'
- '*exit - Say goodbye as the Code Curator, and then abandon inhabiting this persona'
dependencies:
tasks:
- create-code-example.md
- test-code-examples.md
- execute-checklist.md
templates:
- code-example-tmpl.yaml
checklists:
- code-quality-checklist.md
- code-testing-checklist.md
- version-compatibility-checklist.md
data:
- bmad-kb.md
- code-style-guides.md
```
## Startup Context
You are the Code Curator, a master of code quality and example craftsmanship. Your expertise spans clean code principles, testing methodologies, version compatibility management, and cross-platform development. You understand that technical book readers need code examples that work flawlessly.
Think in terms of:
- **Working code** that executes successfully on first try
- **Clean examples** that follow language best practices
- **Thorough testing** across versions and platforms
- **Clear documentation** with helpful comments
- **Error handling** that demonstrates proper techniques
- **Version compatibility** explicitly documented
- **Reproducibility** that ensures consistent results
Your goal is to create code examples that readers can trust, learn from, and adapt to their own projects without frustration.
Always consider:
- Does this code work on the specified versions?
- Have I tested this on the target platforms?
- Are the comments helpful without being verbose?
- Does this follow the language's style guide?
- What could go wrong, and is it handled properly?
- Can a reader easily understand and modify this?
Remember to present all options as numbered lists for easy selection.

102
expansion-packs/bmad-technical-writing/agents/instructional-designer.md Normal file
View File

@ -0,0 +1,102 @@
<!-- Powered by BMAD™ Core -->
# instructional-designer
ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
```yaml
IDE-FILE-RESOLUTION:
- FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies
- Dependencies map to {root}/{type}/{name}
- type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name
- Example: create-doc.md → {root}/tasks/create-doc.md
- IMPORTANT: Only load these files when user requests specific command execution
REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "create book outline"→*create-book-outline, "design learning objectives"→*create-learning-objectives), ALWAYS ask for clarification if no clear match.
activation-instructions:
- STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
- STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
- STEP 3: Greet user with your name/role and mention `*help` command
- DO NOT: Load any other agent files during activation
- ONLY load dependency files when user selects them for execution via command or request of a task
- The agent.customization field ALWAYS takes precedence over any conflicting instructions
- CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material
- MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency
- CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
- When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
- STAY IN CHARACTER!
- CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
agent:
name: Instructional Designer
id: instructional-designer
title: Learning Architecture Specialist
icon: 🎓
whenToUse: Use for learning architecture, pedagogical structure, learning objectives, and instructional scaffolding
customization: null
persona:
role: Learning experience architect and pedagogical structure expert
style: Systematic, learner-focused, progression-aware, methodical
identity: Expert in instructional design, Bloom's taxonomy, scaffolding, cognitive load management
focus: Ensuring readers successfully learn and retain information through well-designed learning experiences
core_principles:
- Learning objectives drive content structure
- Progression follows Bloom's taxonomy (Remember→Understand→Apply→Analyze→Evaluate→Create)
- Scaffolding builds from simple to complex
- Cognitive load must be managed carefully
- Prerequisites must be explicit and validated
- Assessment aligns with learning objectives
- Numbered Options Protocol - Always use numbered lists for user selections
commands:
- '*help - Show numbered list of available commands for selection'
- '*create-book-outline - Run task design-book-outline.md'
- '*create-learning-objectives - Run task create-learning-objectives.md'
- '*design-learning-path - Map prerequisite dependencies and skill progression'
- '*analyze-difficulty-curve - Ensure proper learning progression'
- '*design-assessment-strategy - Create exercises and quizzes aligned with objectives'
- "*apply-learning-framework - Apply Bloom's taxonomy or other pedagogical frameworks"
- '*yolo - Toggle Yolo Mode'
- '*exit - Say goodbye as the Instructional Designer, and then abandon inhabiting this persona'
dependencies:
tasks:
- create-doc.md
- design-book-outline.md
- create-learning-objectives.md
- execute-checklist.md
templates:
- book-outline-tmpl.yaml
- chapter-outline-tmpl.yaml
checklists:
- learning-objectives-checklist.md
- prerequisite-clarity-checklist.md
data:
- bmad-kb.md
- learning-frameworks.md
- book-structures.md
```
## Startup Context
You are the Instructional Designer, a master of learning architecture and pedagogical design. Your expertise spans Bloom's Taxonomy, scaffolding principles, cognitive load theory, and adult learning methodologies. You understand that effective technical books require carefully structured learning paths.
Think in terms of:
- **Learning objectives** that define measurable outcomes
- **Prerequisite mapping** that ensures reader readiness
- **Scaffolding sequences** that build knowledge progressively
- **Cognitive load** that prevents overwhelming learners
- **Assessment alignment** that validates learning outcomes
- **Bloom's progression** from remembering to creating
Your goal is to design book structures and learning paths that enable readers to successfully master technical content, not just consume it.
Always consider:
- What does the reader need to know before starting?
- What will they be able to do after completing this?
- How does this build on previous learning?
- Is the progression appropriate for the target audience?
Remember to present all options as numbered lists for easy selection.

101
expansion-packs/bmad-technical-writing/agents/tutorial-architect.md Normal file
View File

@ -0,0 +1,101 @@
<!-- Powered by BMAD™ Core -->
# tutorial-architect
ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
```yaml
IDE-FILE-RESOLUTION:
- FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies
- Dependencies map to {root}/{type}/{name}
- type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name
- Example: create-doc.md → {root}/tasks/create-doc.md
- IMPORTANT: Only load these files when user requests specific command execution
REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "create tutorial"→*create-tutorial, "design chapter"→*outline-chapter), ALWAYS ask for clarification if no clear match.
activation-instructions:
- STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
- STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
- STEP 3: Greet user with your name/role and mention `*help` command
- DO NOT: Load any other agent files during activation
- ONLY load dependency files when user selects them for execution via command or request of a task
- The agent.customization field ALWAYS takes precedence over any conflicting instructions
- CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material
- MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency
- CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
- When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
- STAY IN CHARACTER!
- CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
agent:
name: Tutorial Architect
id: tutorial-architect
title: Hands-On Instruction Specialist
icon: 📝
whenToUse: Use for step-by-step tutorial design, hands-on exercises, chapter structure, and progressive learning activities
customization: null
persona:
role: Hands-on instruction specialist and tutorial design expert
style: Clear, step-by-step, encouraging, practical, detailed
identity: Expert in breaking down complex topics into actionable steps, scaffolding learning, and creating effective tutorials
focus: Readers can follow along successfully and build working solutions independently
core_principles:
- Every tutorial must be hands-on and practical
- Steps must be clear, actionable, and reproducible
- Expected results must be documented at each step
- Troubleshooting guidance prevents frustration
- Progressive complexity builds confidence
- Practice exercises reinforce learning
- Numbered Options Protocol - Always use numbered lists for user selections
commands:
- '*help - Show numbered list of available commands for selection'
- '*create-tutorial - Design hands-on tutorial section'
- '*outline-chapter - Run task create-chapter-outline.md'
- '*write-walkthrough - Create detailed step-by-step guide'
- '*add-troubleshooting - Document common issues and solutions'
- '*design-exercises - Create practice problems and activities'
- '*write-summary - Create chapter recap and key takeaways'
- '*yolo - Toggle Yolo Mode'
- '*exit - Say goodbye as the Tutorial Architect, and then abandon inhabiting this persona'
dependencies:
tasks:
- create-doc.md
- create-chapter-outline.md
- execute-checklist.md
templates:
- chapter-outline-tmpl.yaml
checklists:
- tutorial-effectiveness-checklist.md
- chapter-completeness-checklist.md
- exercise-difficulty-checklist.md
data:
- bmad-kb.md
- learning-frameworks.md
- book-structures.md
```
## Startup Context
You are the Tutorial Architect, a master of hands-on instruction and step-by-step learning design. Your expertise spans tutorial creation, exercise design, scaffolding techniques, and progressive skill building. You understand that technical readers learn best by doing.
Think in terms of:
- **Step-by-step instructions** that are clear and actionable
- **Expected outcomes** documented at each stage
- **Hands-on practice** that reinforces concepts
- **Progressive complexity** that builds confidence
- **Troubleshooting guidance** that prevents frustration
- **Exercises and challenges** that validate understanding
Your goal is to design tutorials where readers can follow along successfully, build working solutions, and internalize the concepts through practice.
Always consider:
- Can a reader with stated prerequisites complete this independently?
- Are the steps clear and unambiguous?
- What could go wrong, and how do we prevent/address it?
- Does this provide enough practice to build confidence?
Remember to present all options as numbered lists for easy selection.

67
expansion-packs/bmad-technical-writing/checklists/chapter-completeness-checklist.md Normal file
View File

@ -0,0 +1,67 @@
# Chapter Completeness Checklist
Use this checklist to ensure chapters have all necessary components and flow well.
## Introduction
- [ ] Introduction hooks reader with real-world relevance
- [ ] Learning objectives are stated clearly upfront
- [ ] Chapter overview provides roadmap
- [ ] Prerequisites are reminded/referenced
- [ ] Context is provided (how this fits in book)
## Content Structure
- [ ] Concepts are explained before they are used
- [ ] Logical progression from simple to complex
- [ ] Clear section headings guide reader
- [ ] Transitions between sections are smooth
- [ ] No sudden jumps in difficulty
## Learning Objectives Alignment
- [ ] All stated learning objectives are addressed
- [ ] Content supports achieving objectives
- [ ] Practice opportunities align with objectives
- [ ] Objectives are achievable within chapter scope
- [ ] Assessment validates objective completion
## Tutorials and Examples
- [ ] Hands-on tutorials reinforce key concepts
- [ ] Code examples are working and tested
- [ ] Tutorials follow best practices (see tutorial-effectiveness-checklist.md)
- [ ] Balance of theory and practice
- [ ] Examples are realistic and relevant
## Exercises
- [ ] Exercises provide appropriate practice
- [ ] Range from guided to independent challenges
- [ ] Difficulty progression is logical
- [ ] Instructions are clear
- [ ] Solutions or hints are provided (as appropriate)
## Visual Aids
- [ ] Diagrams support understanding where needed
- [ ] Code examples are well-formatted
- [ ] Screenshots show expected results
- [ ] Visuals are clear and labeled
- [ ] Callouts/highlighting used effectively
## Summary
- [ ] Key concepts are recapped clearly
- [ ] Skills checklist shows accomplishments
- [ ] Learning objectives are reviewed
- [ ] Preview of next chapter provides continuity
- [ ] Additional resources offered (if appropriate)
## Consistency
- [ ] Terminology is used consistently
- [ ] Formatting matches book style
- [ ] Code examples follow established patterns
- [ ] Voice and tone are consistent
- [ ] Cross-references are accurate

59
expansion-packs/bmad-technical-writing/checklists/code-quality-checklist.md Normal file
View File

@ -0,0 +1,59 @@
# Code Quality Checklist
Use this checklist to ensure code examples meet quality standards for technical books.
## Style Guide Compliance
- [ ] Code follows language-specific style guide (PEP 8, Airbnb JS, Google Java, etc.)
- [ ] Indentation is consistent and correct
- [ ] Naming conventions are followed
- [ ] Line length limits respected
- [ ] Formatting is consistent throughout
## Naming
- [ ] Variable names are descriptive and meaningful
- [ ] Function/method names clearly describe their purpose
- [ ] No single-letter variables (except in loops/lambdas where conventional)
- [ ] Constants use appropriate naming (UPPER_CASE typically)
- [ ] Class names follow conventions (PascalCase typically)
## Comments
- [ ] Comments explain WHY, not WHAT
- [ ] Complex logic is explained
- [ ] Design decisions are documented
- [ ] Inline comments are used sparingly and purposefully
- [ ] No commented-out code left in examples
## Code Structure
- [ ] No hardcoded values (use constants or configuration)
- [ ] Code is DRY (Don't Repeat Yourself) - unless repetition aids clarity
- [ ] Functions are focused and do one thing well
- [ ] Code is organized logically
- [ ] Imports/dependencies are clearly listed
## Error Handling
- [ ] Appropriate error handling is demonstrated
- [ ] Error messages are meaningful
- [ ] Edge cases are considered
- [ ] Errors are caught at appropriate levels
- [ ] Error handling pattern is language-appropriate
## Best Practices
- [ ] Follows current language best practices
- [ ] Uses modern language features appropriately
- [ ] Avoids deprecated features
- [ ] Security best practices followed (no hardcoded credentials, SQL injection prevention, etc.)
- [ ] Performance considerations addressed where relevant
## Educational Value
- [ ] Code prioritizes clarity over cleverness
- [ ] Examples are simple enough to understand but realistic
- [ ] Code demonstrates the concept clearly
- [ ] No unnecessary complexity
- [ ] Production-ready patterns shown where appropriate

67
expansion-packs/bmad-technical-writing/checklists/code-testing-checklist.md Normal file
View File

@ -0,0 +1,67 @@
# Code Testing Checklist
Use this checklist to ensure all code examples are thoroughly tested.
## Basic Testing
- [ ] Every code example has been executed successfully
- [ ] Code runs on specified version(s) (e.g., Python 3.11+, Node 18+)
- [ ] Output matches documentation
- [ ] No errors or exceptions occur during execution
- [ ] All dependencies install correctly
## Version Compatibility
- [ ] Code tested on minimum supported version
- [ ] Code tested on latest stable version
- [ ] Version-specific behaviors documented
- [ ] Deprecated features avoided
- [ ] Version matrix created and validated
## Platform Testing
- [ ] Code tested on target platforms (Windows/Mac/Linux as applicable)
- [ ] Platform-specific issues identified and documented
- [ ] Path separators handled correctly
- [ ] Line endings appropriate
- [ ] Platform differences noted in documentation
## Edge Cases
- [ ] Empty input tested
- [ ] Null/None values tested
- [ ] Boundary values tested
- [ ] Large datasets tested (if relevant)
- [ ] Error conditions tested
## Error Handling
- [ ] Error cases execute as documented
- [ ] Error messages match documentation
- [ ] Exceptions are caught appropriately
- [ ] Error handling doesn't hide bugs
- [ ] Recovery mechanisms work as expected
## Testing Instructions
- [ ] Setup instructions are complete and accurate
- [ ] Test commands are provided and work
- [ ] Expected output is documented
- [ ] Verification steps are clear
- [ ] Troubleshooting guidance provided
## Dependencies
- [ ] All dependencies are documented
- [ ] Dependency versions are specified
- [ ] Installation instructions are correct
- [ ] No undocumented dependencies
- [ ] Dependency conflicts resolved
## Reproducibility
- [ ] Fresh environment setup works from documented instructions
- [ ] Results are consistent across multiple runs
- [ ] No environment-specific assumptions
- [ ] Configuration steps are complete
- [ ] Verification of setup is possible

67
expansion-packs/bmad-technical-writing/checklists/exercise-difficulty-checklist.md Normal file
View File

@ -0,0 +1,67 @@
# Exercise Difficulty Checklist
Use this checklist to ensure exercises are appropriately challenging and well-designed.
## Difficulty Calibration
- [ ] Exercises match chapter's stated difficulty level
- [ ] Progression from easy to challenging is clear
- [ ] First exercises build confidence
- [ ] Challenge exercises stretch skills appropriately
- [ ] No exercises are impossibly difficult
## Guided Practice (Easier Exercises)
- [ ] Clear step-by-step instructions provided
- [ ] Expected output is shown
- [ ] Hints provided where helpful
- [ ] Similar to tutorial examples
- [ ] Success is achievable with chapter knowledge
## Challenge Problems (Harder Exercises)
- [ ] Require independent problem-solving
- [ ] Build on multiple concepts from chapter
- [ ] Realistic scenarios
- [ ] Solvable with chapter knowledge (no external research required)
- [ ] Solutions or detailed hints available
## Instructions
- [ ] Instructions are clear and unambiguous
- [ ] Required tasks are explicit
- [ ] Success criteria defined
- [ ] Estimated time provided
- [ ] Prerequisites stated
## Estimated Time
- [ ] Time estimates are realistic
- [ ] Range accounts for skill variation (e.g., "15-30 minutes")
- [ ] Setup time included in estimate
- [ ] Total chapter time is reasonable
- [ ] Pacing is appropriate for adult learners
## Solutions
- [ ] Solutions are provided or hints are sufficient
- [ ] Solutions explain approach, not just code
- [ ] Multiple approaches shown when relevant
- [ ] Common mistakes addressed
- [ ] Learning points highlighted in solutions
## Alignment
- [ ] Exercises directly support learning objectives
- [ ] Skills practiced match skills taught
- [ ] No exercises require untaught concepts
- [ ] Realistic application of chapter content
- [ ] Prepares for future chapters where appropriate
## Accessibility
- [ ] Range of difficulty accommodates different skill levels
- [ ] Optional "stretch" exercises for advanced learners
- [ ] Core exercises are achievable by target audience
- [ ] Scaffolding supports less confident learners
- [ ] No exercise blocks chapter completion

59
expansion-packs/bmad-technical-writing/checklists/learning-objectives-checklist.md Normal file
View File

@ -0,0 +1,59 @@
# Learning Objectives Quality Checklist
Use this checklist to validate that learning objectives are well-crafted and effective.
## Action Verb Usage
- [ ] Each objective uses an action verb from Bloom's Taxonomy
- [ ] Verbs are appropriate for the target skill level (Remember/Understand for beginners, Evaluate/Create for advanced)
- [ ] Verbs are specific (not vague like "know" or "understand")
- [ ] Examples: Implement, Analyze, Design, Debug, Evaluate
## Measurability
- [ ] Each objective is measurable and testable
- [ ] Success criteria can be defined
- [ ] Assessment method is clear (exercise, project, quiz, etc.)
- [ ] Objective states what readers will DO, not just "learn"
## Specificity
- [ ] Objectives are specific, not vague or general
- [ ] Technology/tools are named (e.g., "JWT tokens" not "authentication")
- [ ] Context is provided where needed
- [ ] Scope is clear and achievable
## Alignment
- [ ] Objectives align with chapter content
- [ ] Number of objectives is appropriate (3-5 per chapter typically)
- [ ] Objectives build on previous chapters
- [ ] Objectives contribute to book-level learning goals
## Prerequisites
- [ ] Prerequisites for each objective are clear
- [ ] Previous knowledge required is stated
- [ ] Dependencies on prior chapters are explicit
- [ ] External knowledge is identified
## Difficulty Level
- [ ] Difficulty is appropriate for target audience
- [ ] Progression from simple to complex is logical
- [ ] No sudden jumps in complexity
- [ ] Scaffolding supports achieving objectives
## Examples of Good vs Bad
**❌ Bad Objectives:**
- "Understand databases" (vague, not measurable)
- "Learn about authentication" (passive, no action verb)
- "Know React hooks" (not specific, not measurable)
**✅ Good Objectives:**
- "Implement JWT authentication in an Express.js REST API"
- "Analyze database query performance using EXPLAIN"
- "Design reusable React hooks for form state management"

67
expansion-packs/bmad-technical-writing/checklists/prerequisite-clarity-checklist.md Normal file
View File

@ -0,0 +1,67 @@
# Prerequisite Clarity Checklist
Use this checklist to ensure prerequisites are explicit and verifiable.
## Prerequisites Explicitly Listed
- [ ] All prerequisites are clearly stated upfront
- [ ] Previous chapters required are listed
- [ ] External knowledge/skills are identified
- [ ] No hidden assumptions about reader knowledge
- [ ] Prerequisites are easy to find (front of chapter/section)
## External Knowledge
- [ ] Assumed technical knowledge is stated clearly
- [ ] Skill level required is specified (beginner/intermediate/advanced)
- [ ] Domain knowledge assumptions are explicit
- [ ] Reference resources provided for background knowledge
- [ ] No surprise knowledge gaps during chapter
## Software and Tools
- [ ] Required software is listed with version numbers
- [ ] Operating system requirements stated (if applicable)
- [ ] Hardware requirements mentioned (if unusual)
- [ ] Optional vs required tools are distinguished
- [ ] Alternatives mentioned where appropriate
## Installation Instructions
- [ ] Complete installation instructions provided
- [ ] Installation commands are exact and tested
- [ ] Platform-specific instructions given (Windows/Mac/Linux)
- [ ] Common installation issues addressed
- [ ] Links to official documentation included
## Setup Verification
- [ ] Steps to verify successful setup provided
- [ ] Test commands to confirm installation
- [ ] Expected output shown for verification
- [ ] Troubleshooting for failed verification
- [ ] Reader knows definitively they're ready to proceed
## Estimated Setup Time
- [ ] Estimated time for setup is provided
- [ ] Time estimate is realistic
- [ ] Includes download and installation time
- [ ] Accounts for potential troubleshooting
- [ ] Helps readers plan their learning session
## Dependency Management
- [ ] Dependency versions are specified
- [ ] Dependency installation order is clear
- [ ] Dependency conflicts are addressed
- [ ] Lock files or exact versions provided where needed
- [ ] Dependency updates guidance provided
## Previous Chapters
- [ ] Required previous chapters are listed
- [ ] Specific concepts from previous chapters are referenced
- [ ] Optional previous chapters identified
- [ ] Readers can self-assess readiness
- [ ] Review resources provided if needed

59
expansion-packs/bmad-technical-writing/checklists/tutorial-effectiveness-checklist.md Normal file
View File

@ -0,0 +1,59 @@
# Tutorial Effectiveness Checklist
Use this checklist to ensure tutorials are clear, actionable, and effective for learning.
## Step Clarity
- [ ] Each step has clear, actionable instructions
- [ ] Steps are numbered or otherwise clearly sequenced
- [ ] No ambiguous instructions
- [ ] Required actions are explicit (not implied)
- [ ] Steps are in logical order
## Expected Results
- [ ] Expected outcome documented for each step
- [ ] Screenshots or output samples provided where helpful
- [ ] Success indicators are clear
- [ ] Readers know when step is complete
- [ ] Intermediate results are validated
## Reproducibility
- [ ] Reader can complete tutorial independently
- [ ] All required information is provided
- [ ] No assumptions about prior setup
- [ ] Environment setup is documented
- [ ] Tutorial has been tested by someone unfamiliar with material
## Troubleshooting
- [ ] Common issues are identified
- [ ] Solutions for common problems provided
- [ ] Error messages are explained
- [ ] Debugging guidance included
- [ ] Where to get help is documented
## Learning Value
- [ ] Tutorial teaches stated concept clearly
- [ ] Hands-on practice reinforces learning
- [ ] Complexity is appropriate for target audience
- [ ] Builds on previous knowledge appropriately
- [ ] Connects to real-world applications
## Engagement
- [ ] Introduction explains why tutorial matters
- [ ] Motivation is clear (problem being solved)
- [ ] Pace is appropriate (not too fast or slow)
- [ ] Checkpoints validate understanding
- [ ] Summary reinforces key takeaways
## Accessibility
- [ ] Prerequisites are clearly stated
- [ ] Required skill level is appropriate
- [ ] No unexplained jargon
- [ ] Alternative approaches mentioned where relevant
- [ ] Accommodates different learning speeds

75
expansion-packs/bmad-technical-writing/checklists/version-compatibility-checklist.md Normal file
View File

@ -0,0 +1,75 @@
# Version Compatibility Checklist
Use this checklist to ensure code examples support specified versions and version information is clear.
## Version Specification
- [ ] Target versions are explicitly specified (e.g., "Python 3.11+")
- [ ] Minimum version is stated clearly
- [ ] Maximum version tested is documented (if applicable)
- [ ] Version ranges use clear notation (+, -, specific list)
- [ ] Language/framework versions are unambiguous
## Version Testing
- [ ] Code tested on minimum supported version
- [ ] Code tested on latest stable version at time of writing
- [ ] Code tested on intermediate versions where breaking changes exist
- [ ] All specified versions confirmed working
- [ ] Test results documented
## Version-Specific Features
- [ ] Use of version-specific features is noted
- [ ] Features available only in certain versions are documented
- [ ] Backward compatibility considerations addressed
- [ ] Alternative approaches for older versions provided (if supporting multiple)
- [ ] Deprecation warnings acknowledged and addressed
## Deprecated Features
- [ ] No use of deprecated features
- [ ] If deprecated features necessary, warnings included
- [ ] Migration path to current features shown
- [ ] Future compatibility considered
- [ ] Deprecated features only used with explicit justification
## Version Matrix
- [ ] Version compatibility matrix created
- [ ] Matrix includes all target platforms if relevant
- [ ] Known issues documented per version
- [ ] Testing date included in matrix
- [ ] Matrix is up-to-date
## Dependency Versions
- [ ] Dependency versions specified explicitly
- [ ] Dependency version compatibility tested
- [ ] Dependency version ranges documented
- [ ] Lock files provided where appropriate (package-lock.json, Pipfile.lock, etc.)
- [ ] Dependency updates strategy noted
## Migration Notes
- [ ] Guidance for readers on different versions provided
- [ ] Version-specific code variations shown when necessary
- [ ] Breaking changes between versions documented
- [ ] Upgrade path described for version changes
- [ ] Version migration risks identified
## Future-Proofing
- [ ] Code uses stable, well-established features where possible
- [ ] Experimental features are flagged as such
- [ ] Anticipated version changes noted
- [ ] Update strategy for book code discussed
- [ ] Code repository version branches (if supporting multiple versions)
## Documentation
- [ ] README or setup docs specify versions clearly
- [ ] Version numbers in all example code comments
- [ ] Testing environment versions documented
- [ ] Version verification commands provided
- [ ] Troubleshooting for version mismatches included

13
expansion-packs/bmad-technical-writing/config.yaml Normal file
View File

@ -0,0 +1,13 @@
# <!-- Powered by BMAD™ Core -->
name: bmad-technical-writing
version: 0.1.0
short-title: Technical Book Writing Studio
description: >-
Comprehensive AI-powered technical writing framework for technical book
authors, technical trainers, and documentation specialists. Provides
specialized agents, workflows, and tools for planning, writing, and
maintaining technical books with code examples, tutorials, and learning
objectives. Supports publishers like PacktPub, O'Reilly, Manning, and
self-publishing platforms.
author: Wes
slashPrefix: bmad-tw

271
expansion-packs/bmad-technical-writing/data/bmad-kb.md Normal file
View File

@ -0,0 +1,271 @@
# 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

258
expansion-packs/bmad-technical-writing/data/book-structures.md Normal file
View File

@ -0,0 +1,258 @@
# Publisher-Specific Book Structures
This document provides structure guidelines for major technical book publishers and frameworks.
## PacktPub Standard Structure
**Format:** Hands-on, project-based learning
**Typical Structure:**
- 10-15 chapters
- 20-30 pages per chapter
- 300-400 pages total
**Chapter Pattern:**
1. Learning objectives (What you will learn)
2. Introduction with real-world context
3. Hands-on tutorials with code
4. Best practices and tips
5. Summary
6. Further reading/resources
**Key Characteristics:**
- Very practical, code-heavy
- Step-by-step tutorials throughout
- Clear learning outcomes per chapter
- Real-world examples
- Beginner to intermediate focus
---
## O'Reilly Learning Path Structure
**Format:** Conceptual→Practical progression with depth
**Typical Structure:**
- Part-based organization (3-5 parts)
- 12-20 chapters across parts
- Varying chapter lengths (15-40 pages)
- 400-600 pages total
**Part Pattern:**
- **Part I**: Foundations and core concepts
- **Part II**: Intermediate techniques
- **Part III**: Advanced topics
- **Part IV**: Real-world applications (optional)
**Chapter Pattern:**
1. Concept introduction
2. Detailed explanation with diagrams
3. Code examples and experiments
4. Exercises for practice
5. Summary and what's next
**Key Characteristics:**
- Rich code examples with explanations
- Sidebars for deep dives
- Callouts for warnings/tips
- Comprehensive index
- Intermediate to advanced focus
- Theory balanced with practice
---
## Manning In-Depth Tutorial Structure
**Format:** Deep tutorial with progressive build approach
**Typical Structure:**
- 12-15 chapters
- 25-35 pages per chapter
- 350-500 pages total
**Chapter Pattern:**
1. Motivating example (real-world problem)
2. Concept explanation (theory)
3. Hands-on tutorial (implementation)
4. Iterative improvements
5. Real-world application
6. Exercises throughout
**Key Characteristics:**
- Start with working example, then explain
- Progressive complexity (build up incrementally)
- MEAP (Manning Early Access Program) format
- Code listings are numbered and referenced
- Exercises integrated into flow, not just at end
- Intermediate to advanced focus
---
## Diátaxis Framework (Publisher-Agnostic)
**Four Documentation Types:**
### 1. Tutorials (Learning-Oriented)
- Take reader through series of steps
- Help beginners get started
- Minimal explanation, maximum doing
- Reliable and repeatable
### 2. How-To Guides (Task-Oriented)
- Show how to solve specific problem
- Assume some knowledge
- Series of steps to achieve goal
- Practical and focused
### 3. Explanation (Understanding-Oriented)
- Clarify and illuminate
- Provide background and context
- Make connections
- Discuss alternatives and decisions
### 4. Reference (Information-Oriented)
- Describe the machinery
- Accurate and complete
- Structure by API/function
- Consistent format
**Application to Technical Books:**
- Early chapters: Tutorials + some Explanation
- Middle chapters: How-To Guides + Explanation
- Later chapters: Advanced How-To + deeper Explanation
- Appendices: Reference material
---
## Chapter Micro-Structures
### Introduction Section (1-2 pages)
- Hook with real-world problem
- Overview of chapter content
- Prerequisites reminder
- What readers will accomplish
### Main Content Section (3-6 pages each)
- Concept explanation
- Code example with walkthrough
- Common mistakes to avoid
- Best practices
### Exercises Section (2-3 pages)
- Guided practice (3-4 exercises)
- Challenge problems (1-2 harder)
- Solutions or hints
### Summary Section (1 page)
- Key concepts recap
- Skills checklist
- Preview of next chapter
- Additional resources
---
## Self-Publishing Best Practices
**Platforms:** Leanpub, KDP, Gumroad
**Flexibility:** No strict structure requirements
**Recommendations:**
- Follow general best practices from major publishers
- Typical range: 200-500 pages
- Clear table of contents
- Consistent formatting
- Professional editing
- Code repository on GitHub
- Regular updates possible (advantage of self-publishing)
**Consider:**
- Audience expectations (what format do they expect?)
- Competition (what structure do similar books use?)
- Your teaching style (tutorial vs conceptual vs reference)
- Maintenance burden (easier to update modular structure)
---
## General Structure Guidelines
**Front Matter:**
- Title page
- Copyright
- Table of contents
- Preface/Introduction
- About the author
- About the reviewers (if applicable)
- Prerequisites
- How to use this book
- Conventions used
- Companion code repository
**Main Content:**
- Organized into parts (optional) and chapters
- Progressive difficulty
- Consistent chapter structure
- Cross-references between chapters
**Back Matter:**
- Appendices (reference material)
- Glossary
- Index
- Additional resources
- Answer key (if solutions not inline)
---
## Choosing the Right Structure
**Choose PacktPub style for:**
- Beginner-focused content
- Very practical, project-based books
- Clear learning paths
- Hands-on tutorials
**Choose O'Reilly style for:**
- Intermediate to advanced content
- Conceptual depth required
- Multiple parts with different focus
- Comprehensive reference value
**Choose Manning style for:**
- Deep tutorial approach
- Progressive build-up
- Iterative improvement examples
- Strong narrative flow
**Choose Diátaxis framework for:**
- Documentation-style books
- Multiple content types needed
- Clear separation of concerns
- Reference-heavy content

473
expansion-packs/bmad-technical-writing/data/code-style-guides.md Normal file
View File

@ -0,0 +1,473 @@
# Code Style Guides for Technical Writing
This document summarizes language-specific coding standards for technical book code examples.
## Universal Code Example Standards
These apply to ALL code examples regardless of language:
### Readability First
- Use descriptive variable and function names
- Prefer clarity over cleverness
- Add inline comments for WHY, not WHAT
- Keep functions focused and small
### Educational Code vs Production Code
Technical book code should prioritize:
- **Clarity** over performance (unless teaching performance)
- **Explicitness** over brevity
- **Simplicity** over DRY (some repetition acceptable for clarity)
- **Readability** over advanced language features
### Comments
```
❌ Bad: Obvious comments
// increment counter
counter++;
✅ Good: Explain decisions
// Use exponential backoff to avoid overwhelming API during retry
await sleep(Math.pow(2, retryCount) * 1000);
```
### Error Handling
- Always demonstrate proper error handling
- Show common error scenarios
- Provide meaningful error messages
- Use language-appropriate patterns
### Magic Numbers
```
❌ Bad
if (age >= 18) { ... }
✅ Good
const MINIMUM_AGE = 18;
if (age >= MINIMUM_AGE) { ... }
```
---
## Python (PEP 8)
**Official Style Guide:** PEP 8 - Style Guide for Python Code
### Key Principles
**Indentation:**
- Use 4 spaces (not tabs)
- No mixing tabs and spaces
**Line Length:**
- Maximum 79 characters for code
- Maximum 72 for comments and docstrings
**Naming Conventions:**
```python
# Variables and functions: snake_case
user_name = "Alice"
def calculate_total(items): ...
# Constants: UPPER_CASE
MAX_CONNECTIONS = 100
API_TIMEOUT = 30
# Classes: PascalCase
class UserAccount: ...
class DatabaseConnection: ...
# Private: leading underscore
_internal_variable = 42
def _private_method(self): ...
```
**Imports:**
```python
# Standard library first
import os
import sys
# Then third-party
import requests
import numpy as np
# Then local imports
from myapp import models
from myapp.utils import helpers
# Avoid wildcard imports
from module import * # ❌ Bad
from module import SpecificClass # ✅ Good
```
**Docstrings:**
```python
def fetch_user(user_id: int) -> dict:
"""
Fetch user data from the database.
Args:
user_id: The unique identifier for the user
Returns:
Dictionary containing user data
Raises:
UserNotFoundError: If user doesn't exist
"""
...
```
**Type Hints (Python 3.5+):**
```python
def greet(name: str) -> str:
return f"Hello, {name}"
def process_items(items: list[dict]) -> None:
...
```
---
## JavaScript (Airbnb Style Guide)
**Official Style Guide:** Airbnb JavaScript Style Guide (github.com/airbnb/javascript)
### Key Principles
**Variables:**
```javascript
// Use const for values that won't be reassigned
const API_URL = 'https://api.example.com';
const user = { name: 'Alice' };
// Use let for values that will change
let counter = 0;
// Never use var
var oldStyle = 'bad'; // ❌
```
**Naming Conventions:**
```javascript
// Variables and functions: camelCase
const userName = "Alice";
function calculateTotal(items) { ... }
// Constants: UPPER_CASE (by convention)
const MAX_RETRY_COUNT = 3;
const API_TIMEOUT = 30000;
// Classes: PascalCase
class UserAccount { ... }
class DatabaseConnection { ... }
// Private (by convention): leading underscore
class Example {
_privateMethod() { ... }
}
```
**Functions:**
```javascript
// Arrow functions for callbacks
const numbers = [1, 2, 3];
const doubled = numbers.map((n) => n * 2);
// Named functions for clarity
function processOrder(order) {
// Implementation
}
// Avoid function hoisting confusion
// Declare before use
const helper = () => { ... };
helper();
```
**Strings:**
```javascript
// Use template literals for interpolation
const message = `Hello, ${userName}!`; // ✅ Good
const bad = 'Hello, ' + userName + '!'; // ❌ Avoid
// Use single quotes for simple strings
const apiKey = 'abc123';
```
**Objects and Arrays:**
```javascript
// Use shorthand
const name = 'Alice';
const user = { name }; // ✅ Good (shorthand)
const user2 = { name: name }; // ❌ Verbose
// Destructuring
const { id, email } = user;
const [first, second] = array;
// Spread operator
const newUser = { ...user, status: 'active' };
const newArray = [...oldArray, newItem];
```
---
## Java (Google Style Guide)
**Official Style Guide:** Google Java Style Guide
### Key Principles
**Indentation:**
- Use 2 spaces (not 4, not tabs)
- Continuation indent: 4 spaces
**Naming Conventions:**
```java
// Classes: PascalCase
public class UserAccount { }
public class DatabaseConnection { }
// Methods and variables: camelCase
public void calculateTotal() { }
private int userCount = 0;
// Constants: UPPER_CASE
private static final int MAX_CONNECTIONS = 100;
public static final String API_URL = "https://api.example.com";
// Packages: lowercase
package com.example.myapp;
```
**Braces:**
```java
// Braces on same line (K&R style)
if (condition) {
// code
} else {
// code
}
// Always use braces, even for single statements
if (condition) {
doSomething(); // ✅ Good
}
if (condition)
doSomething(); // ❌ Bad (no braces)
```
**Javadoc:**
```java
/**
* Fetches user data from the database.
*
* @param userId the unique identifier for the user
* @return User object containing user data
* @throws UserNotFoundException if user doesn't exist
*/
public User fetchUser(int userId) throws UserNotFoundException {
// Implementation
}
```
**Ordering:**
```java
public class Example {
// 1. Static fields
private static final int CONSTANT = 42;
// 2. Instance fields
private int count;
// 3. Constructor
public Example() { }
// 4. Public methods
public void doSomething() { }
// 5. Private methods
private void helper() { }
}
```
---
## Code Example Best Practices by Language
### Python
```python
# ✅ Good Example
def authenticate_user(username: str, password: str) -> dict:
"""
Authenticate user and return JWT token.
Args:
username: User's login name
password: User's password (will be hashed)
Returns:
Dictionary with 'token' and 'expires_at' keys
Raises:
AuthenticationError: If credentials are invalid
"""
# Hash password for comparison
password_hash = hash_password(password)
# Query database
user = User.query.filter_by(username=username).first()
if not user or user.password_hash != password_hash:
raise AuthenticationError("Invalid credentials")
# Generate JWT token with 1-hour expiration
token = jwt.encode(
{"user_id": user.id, "exp": datetime.utcnow() + timedelta(hours=1)},
SECRET_KEY,
algorithm="HS256",
)
return {"token": token, "expires_at": datetime.utcnow() + timedelta(hours=1)}
```
### JavaScript/Node.js
```javascript
// ✅ Good Example
async function authenticateUser(username, password) {
// Hash password for comparison
const passwordHash = await bcrypt.hash(password, SALT_ROUNDS);
// Query database
const user = await User.findOne({ where: { username } });
if (!user || !(await bcrypt.compare(password, user.passwordHash))) {
throw new AuthenticationError('Invalid credentials');
}
// Generate JWT token with 1-hour expiration
const token = jwt.sign({ userId: user.id }, SECRET_KEY, { expiresIn: '1h' });
return {
token,
expiresAt: new Date(Date.now() + 3600000), // 1 hour from now
};
}
```
### Java
```java
// ✅ Good Example
public class AuthService {
private static final int TOKEN_EXPIRY_HOURS = 1;
/**
* Authenticates user and returns JWT token.
*
* @param username user's login name
* @param password user's password (will be hashed)
* @return AuthResponse containing token and expiration
* @throws AuthenticationException if credentials are invalid
*/
public AuthResponse authenticateUser(String username, String password)
throws AuthenticationException {
// Hash password for comparison
String passwordHash = PasswordUtil.hash(password);
// Query database
User user = userRepository.findByUsername(username);
if (user == null || !user.getPasswordHash().equals(passwordHash)) {
throw new AuthenticationException("Invalid credentials");
}
// Generate JWT token with 1-hour expiration
String token = Jwts.builder()
.setSubject(String.valueOf(user.getId()))
.setExpiration(new Date(System.currentTimeMillis() + TimeUnit.HOURS.toMillis(TOKEN_EXPIRY_HOURS)))
.signWith(SignatureAlgorithm.HS256, SECRET_KEY)
.compact();
return new AuthResponse(token, new Date(System.currentTimeMillis() + TimeUnit.HOURS.toMillis(TOKEN_EXPIRY_HOURS)));
}
}
```
---
## Testing Code Examples
For technical books, include test examples:
### Python (pytest)
```python
def test_authenticate_user_success():
"""Test successful authentication."""
response = authenticate_user("alice", "correct_password")
assert "token" in response
assert response["expires_at"] > datetime.utcnow()
def test_authenticate_user_invalid_password():
"""Test authentication with wrong password."""
with pytest.raises(AuthenticationError):
authenticate_user("alice", "wrong_password")
```
### JavaScript (Jest)
```javascript
describe('authenticateUser', () => {
it('returns token for valid credentials', async () => {
const response = await authenticateUser('alice', 'correct_password');
expect(response).toHaveProperty('token');
expect(response.expiresAt).toBeInstanceOf(Date);
});
it('throws error for invalid password', async () => {
await expect(authenticateUser('alice', 'wrong_password')).rejects.toThrow(AuthenticationError);
});
});
```
---
## Official Style Guide Links
- **Python PEP 8**: https://peps.python.org/pep-0008/
- **JavaScript Airbnb**: https://github.com/airbnb/javascript
- **Java Google**: https://google.github.io/styleguide/javaguide.html
- **TypeScript**: https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html
- **Go**: https://go.dev/doc/effective_go
- **Rust**: https://doc.rust-lang.org/book/appendix-07-syntax-guide.html
- **C#**: https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions
Always check official documentation for your target language version.

426
expansion-packs/bmad-technical-writing/data/learning-frameworks.md Normal file
View File

@ -0,0 +1,426 @@
# Learning Frameworks for Technical Writing
This document provides pedagogical frameworks essential for designing effective technical books and tutorials.
## Bloom's Taxonomy
Bloom's Taxonomy provides a hierarchy of cognitive skills from simple recall to complex creation. Use it to design learning progression and create appropriate learning objectives.
### The Six Levels
#### 1. Remember (Lowest Level)
**Description:** Recall facts, terms, basic concepts
**Action Verbs:**
- List, Define, Name, Identify, Label
- Describe, Recognize, Recall, State
**Example Learning Objectives:**
- "List the main HTTP methods (GET, POST, PUT, DELETE)"
- "Identify the components of a REST API"
- "Define what JWT authentication means"
**Assessment:** Multiple choice, matching, simple recall questions
---
#### 2. Understand
**Description:** Explain ideas or concepts
**Action Verbs:**
- Explain, Describe, Summarize, Interpret
- Compare, Classify, Discuss, Paraphrase
**Example Learning Objectives:**
- "Explain how JWT tokens provide stateless authentication"
- "Describe the difference between synchronous and asynchronous code"
- "Summarize the benefits of using TypeScript over JavaScript"
**Assessment:** Short answer explanations, concept mapping
---
#### 3. Apply
**Description:** Use information in new situations
**Action Verbs:**
- Implement, Execute, Use, Apply
- Demonstrate, Build, Solve, Show
**Example Learning Objectives:**
- "Implement user authentication using Passport.js"
- "Build a REST API with CRUD operations"
- "Use async/await to handle asynchronous operations"
**Assessment:** Coding exercises, hands-on projects
---
#### 4. Analyze
**Description:** Draw connections, distinguish between parts
**Action Verbs:**
- Analyze, Compare, Contrast, Examine
- Debug, Troubleshoot, Differentiate, Investigate
**Example Learning Objectives:**
- "Analyze database query performance using EXPLAIN"
- "Debug memory leaks in Node.js applications"
- "Compare SQL vs NoSQL for specific use cases"
**Assessment:** Debugging tasks, performance analysis, case studies
---
#### 5. Evaluate
**Description:** Justify decisions, make judgments
**Action Verbs:**
- Evaluate, Assess, Critique, Judge
- Optimize, Recommend, Justify, Argue
**Example Learning Objectives:**
- "Evaluate trade-offs between different caching strategies"
- "Assess security vulnerabilities using OWASP guidelines"
- "Optimize API response times through profiling"
**Assessment:** Code reviews, architecture critiques, optimization challenges
---
#### 6. Create (Highest Level)
**Description:** Produce new or original work
**Action Verbs:**
- Design, Develop, Create, Construct
- Architect, Formulate, Author, Devise
**Example Learning Objectives:**
- "Design a scalable microservices architecture"
- "Develop a CI/CD pipeline for automated deployment"
- "Create a custom authentication system with MFA"
**Assessment:** Original projects, system design, architectural proposals
---
### Applying Bloom's to Book Structure
**Early Chapters (Remember + Understand):**
- Define terminology
- Explain core concepts
- Simple examples
**Middle Chapters (Apply + Analyze):**
- Hands-on implementation
- Debugging exercises
- Comparative analysis
**Late Chapters (Evaluate + Create):**
- Optimization challenges
- Design decisions
- Original projects
---
## Scaffolding Principles
Scaffolding provides temporary support structures that help learners achieve more than they could independently, then gradually removes support as competence grows.
### Core Principles
#### 1. Start with Concrete Examples
- Show working code first
- Use real-world scenarios
- Demonstrate before explaining theory
- Tangible results build confidence
**Example:**
```
❌ Poor: "RESTful APIs follow stateless client-server architecture..."
✅ Better: "Here's a working API endpoint. Let's see what happens when we call it, then understand why it works this way."
```
#### 2. Progress to Abstract Concepts
- After concrete understanding, introduce theory
- Connect examples to general principles
- Explain underlying concepts
- Build mental models
**Progression:**
1. Working example
2. What it does (concrete)
3. How it works (mechanism)
4. Why it works (theory)
5. When to use it (application)
#### 3. Build on Prior Knowledge
- Explicitly state prerequisites
- Reference previous chapters
- Activate existing knowledge
- Connect new to known
**Example:**
```
"In Chapter 3, we learned about promises. Async/await is syntactic sugar that makes promises easier to work with..."
```
#### 4. Gradual Complexity Increase
- Start simple, add features incrementally
- Introduce one new concept at a time
- Build up to complex examples
- Avoid overwhelming cognitive load
**Progressive Build:**
1. Basic function
2. Add error handling
3. Add logging
4. Add caching
5. Add advanced features
#### 5. Guided → Independent Practice
- Start with step-by-step tutorials
- Reduce guidance gradually
- End with independent challenges
- Build reader confidence
**Practice Progression:**
1. **Guided**: "Follow these steps exactly..."
2. **Partial guidance**: "Now implement X using the same pattern..."
3. **Independent**: "Build feature Y on your own..."
4. **Challenge**: "Design and implement Z..."
---
## Cognitive Load Management
Cognitive Load Theory explains how working memory limitations affect learning. Technical books must manage cognitive load carefully.
### Types of Cognitive Load
#### 1. Intrinsic Load
- Inherent difficulty of the material
- Cannot be reduced without changing content
- Manage by proper sequencing
**Strategy:** Break complex topics into smaller chunks
#### 2. Extraneous Load
- Unnecessary cognitive effort
- Caused by poor instruction design
- CAN and SHOULD be minimized
**Causes:**
- Confusing explanations
- Unclear code examples
- Missing context
- Poor organization
#### 3. Germane Load
- Effort required to build understanding
- Desirable difficulty
- Promotes schema construction
**Strategy:** Use exercises and practice that build understanding
### Cognitive Load Management Strategies
#### 1. Chunking Information
- Break content into digestible pieces
- Group related concepts together
- Use clear section headings
- Limit scope of each section
**Example:**
```
❌ Poor: One 40-page chapter on "Database Design"
✅ Better: Four 10-page chapters: "Schema Design", "Indexing", "Normalization", "Optimization"
```
#### 2. Progressive Disclosure
- Introduce information when needed
- Don't front-load everything
- Just-in-time teaching
- Hide complexity until required
**Example:**
```
Chapter 1: Basic SQL queries (SELECT, WHERE)
Chapter 2: Joins and relationships
Chapter 3: Advanced queries (subqueries, CTEs)
Chapter 4: Optimization and indexes
```
#### 3. Worked Examples Before Practice
- Show complete solutions first
- Explain step-by-step
- Then ask readers to practice
- Reduces cognitive load of problem-solving while learning
**Pattern:**
1. Show complete example with explanation
2. Show similar example with partial explanation
3. Ask reader to complete similar task
4. Provide independent challenge
#### 4. Dual Coding (Text + Visual)
- Use diagrams to complement text
- Code examples with visual flow diagrams
- Screenshots of results
- Reduces cognitive load by distributing across channels
**Effective Visuals:**
- Architecture diagrams
- Flow charts
- Sequence diagrams
- Database schemas
- API request/response flows
---
## Adult Learning Principles
Adult learners have specific characteristics that affect technical book design.
### Key Principles
#### 1. Adults are Self-Directed
- Provide clear learning paths
- Explain the "why" not just "what"
- Allow exploration and experimentation
- Respect prior experience
**Application:**
- Clear objectives upfront
- Optional "deep dive" sections
- Multiple approaches shown
- Encourage adaptation to needs
#### 2. Adults Need Relevance
- Real-world examples
- Practical applications
- Career relevance
- Immediate applicability
**Application:**
- Start chapters with real-world problems
- Show industry use cases
- Explain job market demand
- Provide production-ready patterns
#### 3. Adults are Problem-Oriented
- Learn best through solving problems
- Prefer practical over theoretical
- Want working solutions
- Value hands-on practice
**Application:**
- Problem-based learning approach
- Tutorials over lectures
- Working code examples
- Real projects
#### 4. Adults Bring Experience
- Acknowledge existing knowledge
- Build on prior experience
- Allow knowledge transfer
- Respect diverse backgrounds
**Application:**
- State prerequisites clearly
- Reference common experiences
- Compare to known technologies
- Provide multiple analogies
---
## Applying These Frameworks Together
### Book-Level Application
**Part I: Foundations (Bloom's: Remember + Understand)**
- Scaffolding: Concrete examples first
- Cognitive Load: Small chunks, progressive disclosure
- Adult Learning: Show relevance and practical use
**Part II: Application (Bloom's: Apply + Analyze)**
- Scaffolding: Guided tutorials with gradual independence
- Cognitive Load: Worked examples before practice
- Adult Learning: Problem-based approach
**Part III: Mastery (Bloom's: Evaluate + Create)**
- Scaffolding: Independent challenges
- Cognitive Load: Integrate prior knowledge
- Adult Learning: Real-world projects
### Chapter-Level Application
1. **Introduction**: Activate prior knowledge (scaffolding), show relevance (adult learning)
2. **Concepts**: Manage cognitive load (chunking), start concrete (scaffolding)
3. **Tutorials**: Worked examples (cognitive load), problem-oriented (adult learning)
4. **Exercises**: Progress to independence (scaffolding), higher Bloom's levels
5. **Summary**: Reinforce learning, connect to next chapter
---
## Resources and Further Reading
- **Bloom's Taxonomy Revised**: Anderson & Krathwohl (2001)
- **Cognitive Load Theory**: Sweller, Ayres, & Kalyuga (2011)
- **Adult Learning Theory**: Knowles (1984)
- **Instructional Design**: Gagne's Nine Events of Instruction
- **Technical Writing**: Diátaxis framework (documentation.divio.com)

34
expansion-packs/bmad-technical-writing/data/publisher-guidelines.md Normal file
View File

@ -0,0 +1,34 @@
# Publisher Guidelines
**Note:** This is a Sprint 1 placeholder. Full publisher-specific guidelines will be added in Sprint 2.
## Current Content
Basic publisher structure information is available in `book-structures.md`.
## Sprint 2 Additions
Full guidelines will include:
- PacktPub submission requirements (from research section 11p)
- O'Reilly format and style requirements (from research section 11q)
- Manning MEAP process and requirements (from research section 11r)
- Self-publishing platform standards (from research section 11s)
- Formatting specifications per publisher
- Submission checklists
- Review process expectations
- Royalty and contract considerations
## Temporary Reference
For Sprint 1, refer to:
- `book-structures.md` for general structure patterns
- Publisher websites for official submission guidelines
- `bmad-kb.md` for publisher-specific considerations
## Resources
- PacktPub Author Hub: https://www.packtpub.com/authors
- O'Reilly Author Resources: https://www.oreilly.com/work-with-us.html
- Manning Author Guidelines: https://www.manning.com/write-for-us

60
expansion-packs/bmad-technical-writing/data/technical-writing-standards.md Normal file
View File

@ -0,0 +1,60 @@
# Technical Writing Standards
**Note:** This is a Sprint 1 placeholder. Full technical writing standards will be added in Sprint 2.
## Current Guidance
Basic writing principles are embedded in:
- Agent personas (emphasis on clarity, consistency)
- Task workflows (quality checkpoints)
- Checklists (validation criteria)
## Sprint 2 Additions
Full standards will include:
- Clarity principles (from research section 11x)
- Consistency requirements (from research section 11y)
- Accessibility guidelines (from research section 11z)
- Structure best practices (from research section 11za)
- Voice and tone guidelines
- Formatting conventions
- Cross-reference standards
- Glossary and index creation
## Key Principles (Interim Guidance)
### Clarity
- Use simple, direct language
- Explain technical terms on first use
- Provide examples for abstract concepts
- Break complex ideas into steps
### Consistency
- Use terminology consistently
- Follow established patterns
- Maintain uniform formatting
- Apply style guide uniformly
### Accessibility
- Consider diverse reader backgrounds
- Provide multiple explanations when helpful
- Use inclusive language
- Ensure code examples work universally
### Structure
- Logical progression of topics
- Clear section headings
- Predictable chapter patterns
- Strong transitions between sections
## Resources
- Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
- Google Developer Documentation Style Guide: https://developers.google.com/style
- Write the Docs: https://www.writethedocs.org/guide/writing/style-guides/

305
expansion-packs/bmad-technical-writing/tasks/create-chapter-outline.md Normal file
View File

@ -0,0 +1,305 @@
<!-- Powered by BMAD™ Core -->
# Create Chapter Outline
---
task:
id: create-chapter-outline
name: Create Chapter Outline
description: Structure detailed chapter plan with learning objectives and content breakdown
persona_default: tutorial-architect
inputs:
- chapter-number
- chapter-topic
- book-outline-reference
steps:
- Review book outline context and learning path
- Define chapter number and title
- Identify 3-5 learning objectives using action verbs
- List prerequisites clearly (previous chapters, external knowledge)
- Plan introduction section (hook, overview, relevance)
- Break down main content sections with tutorials
- Design exercises and practice activities
- Create summary structure
- List code files needed
- Validate against book-level learning path
- Use template chapter-outline-tmpl.yaml with create-doc.md task
- Run execute-checklist.md with prerequisite-clarity-checklist.md
output: docs/outlines/chapter-{{chapter_number}}-outline.md
---
## Purpose
This task guides you through creating a detailed chapter outline that balances theory, hands-on practice, and progressive skill building. A solid outline makes writing the chapter much easier.
## Prerequisites
Before starting this task:
- Book outline completed (provides context and learning path)
- Chapter topic and position in book determined
- Access to book-structures.md knowledge base
- Understanding of target audience
## Workflow Steps
### 1. Review Book Outline Context
Understand this chapter's role:
- Where does this chapter fit in the book?
- What chapters come before/after?
- What are the book-level learning objectives?
- What is the overall learning progression?
### 2. Define Chapter Metadata
Establish basic information:
- **Chapter number**: Position in book
- **Chapter title**: Clear, descriptive
- **Estimated page count**: Typical ranges 15-30 pages
- **Reading time**: Estimated time to complete (2-4 hours typical)
- **Difficulty level**: Beginner, Intermediate, Advanced
### 3. Identify Learning Objectives
Create 3-5 measurable objectives (see create-learning-objectives.md):
**Use action verbs:**
- "Implement user authentication using JWT tokens"
- "Debug async code using browser DevTools"
- "Optimize database queries for better performance"
**Ensure objectives:**
- Build on previous chapters
- Align with book learning path
- Are measurable and specific
- Match target difficulty level
### 4. List Prerequisites Explicitly
Define what readers need before starting:
**Previous Chapters:**
- "Chapter 3: Database Fundamentals"
- "Chapter 5: RESTful API Design"
**External Knowledge:**
- "Basic JavaScript ES6 syntax"
- "Understanding of HTTP request/response cycle"
**Software/Tools:**
- "Node.js 18+ installed"
- "PostgreSQL 14+ running locally"
- "VS Code or similar IDE"
**Setup Time:**
- "Approximately 30 minutes for environment setup"
### 5. Plan Introduction Section
Design the chapter opening (1-2 pages):
**Hook/Motivation:**
- Real-world problem this chapter solves
- Why this topic matters
- Common pain points addressed
**Overview:**
- What topics will be covered
- How sections connect
- What readers will build
**Relevance:**
- How this fits into larger application development
- Industry use cases
- Career relevance
### 6. Break Down Main Content Sections
For each major section of the chapter:
**Section Structure:**
1. **Section Title**: Descriptive and clear
2. **Concept Explanation**: Theory and background (2-4 pages)
3. **Tutorial/Walkthrough**: Hands-on implementation (3-6 pages)
4. **Code Examples**: List files and purpose
5. **Visuals**: Diagrams, screenshots needed
6. **Common Mistakes**: Pitfalls to highlight
7. **Troubleshooting**: Common issues and solutions
**Typical Chapter Structure:**
- **Introduction** (1-2 pages)
- **Section 1: Foundations** (5-7 pages)
- **Section 2: Implementation** (6-8 pages)
- **Section 3: Advanced Topics** (4-6 pages)
- **Exercises** (2-3 pages)
- **Summary** (1 page)
### 7. Design Exercises and Challenges
Create practice opportunities:
**Guided Practice (3-4 exercises):**
- Step-by-step instructions provided
- Builds confidence
- Reinforces key concepts
**Challenge Problems (1-2):**
- Requires independent problem-solving
- Tests deeper understanding
- Stretches skills
**For Each Exercise:**
- Clear instructions
- Expected outcome
- Difficulty level
- Estimated time
- Solution provided? (yes/no/hints only)
### 8. Plan Summary Section
Design chapter conclusion (1 page):
**Key Concepts Recap:**
- Bullet list of main takeaways
- Visual summary if helpful
**Skills Checklist:**
- "You can now..."
- Measurable accomplishments
- Links back to learning objectives
**Next Steps:**
- Preview of next chapter
- How skills will be built upon
- Optional advanced reading
### 9. List Code Files
Document all code examples:
**For Each File:**
- Filename (e.g., `auth-middleware.js`)
- Purpose (brief description)
- Language/version (e.g., "Node.js 18+")
- Dependencies (packages required)
- Testing requirements (unit tests needed?)
**Example:**
```
Code Files:
1. user-model.js - User database schema and validation
2. auth-controller.js - Authentication route handlers
3. jwt-utils.js - Token generation and verification utilities
4. auth.test.js - Unit tests for authentication logic
```
### 10. Validate Against Book Learning Path
Ensure chapter fits progression:
- Does this build on previous chapters naturally?
- Are prerequisites from earlier chapters met?
- Does this prepare readers for upcoming chapters?
- Is difficulty progression appropriate?
- Are there any gaps in coverage?
### 11. Generate Chapter Outline
Use the create-doc.md task with chapter-outline-tmpl.yaml template to create the structured outline document.
### 12. Run Quality Checklist
Execute prerequisite-clarity-checklist.md:
- [ ] Prerequisites explicitly listed
- [ ] External knowledge stated
- [ ] Required software documented
- [ ] Installation instructions provided
- [ ] Setup verification steps included
## Success Criteria
A completed chapter outline should have:
- [ ] Clear chapter number and title
- [ ] 3-5 measurable learning objectives
- [ ] Prerequisites explicitly documented
- [ ] Engaging introduction planned
- [ ] Main sections broken down with page estimates
- [ ] Tutorials and code examples identified
- [ ] Exercises and challenges designed
- [ ] Summary structure defined
- [ ] Code files list complete
- [ ] Validates against book learning path
- [ ] prerequisite-clarity-checklist.md passed
## Common Pitfalls to Avoid
- **Too much content**: Better to go deep on fewer topics
- **No hands-on practice**: Technical books need tutorials
- **Unclear prerequisites**: Be explicit about what readers need
- **Poor progression**: Concepts should build logically
- **Missing exercises**: Practice is essential for learning
- **Vague learning objectives**: Use specific, measurable outcomes
- **No troubleshooting**: Anticipate common issues
- **Inconsistent difficulty**: Avoid sudden complexity jumps
## Chapter Structure Patterns
**Tutorial-Heavy (PacktPub style):**
- Brief theory
- Extensive step-by-step walkthrough
- Multiple small exercises
- Project-based learning
**Concept-Heavy (O'Reilly style):**
- In-depth explanation
- Multiple examples
- Exercises after each concept
- Real-world applications
**Progressive Build (Manning style):**
- Introduce concept
- Simple implementation
- Iterate with improvements
- Advanced techniques
- Final polished version
## Next Steps
After completing chapter outline:
1. Review with technical expert or beta reader
2. Share with editor for feedback
3. Begin drafting chapter content
4. Create code examples (create-code-example.md)
5. Develop exercises and solutions
6. Test all code examples (test-code-examples.md)

244
expansion-packs/bmad-technical-writing/tasks/create-code-example.md Normal file
View File

@ -0,0 +1,244 @@
<!-- Powered by BMAD™ Core -->
# Create Code Example
---
task:
id: create-code-example
name: Create Code Example
description: Develop working, tested, documented code example with explanation
persona_default: code-curator
inputs:
- concept-to-demonstrate
- programming-language
- target-version
steps:
- Identify learning objective for this code example
- Choose appropriate complexity level for target audience
- Write working code with inline comments
- Test code for correctness on target version
- Write detailed explanation connecting code to concepts
- Document prerequisites and dependencies
- Add common mistakes section
- Create variations and extensions section
- Define testing approach
- Use template code-example-tmpl.yaml with create-doc.md task
- Run execute-checklist.md with code-quality-checklist.md
- Run execute-checklist.md with code-testing-checklist.md
- Run execute-checklist.md with version-compatibility-checklist.md
output: docs/code-examples/{{example-name}}-example.md
---
## Purpose
This task guides you through creating high-quality code examples that readers can trust, understand, and adapt. Every code example must work perfectly, follow best practices, and include comprehensive explanation.
## Prerequisites
Before starting this task:
- Clear understanding of the concept to demonstrate
- Target programming language and version
- Access to code-style-guides.md knowledge base
- Ability to test code on target platform(s)
## Workflow Steps
### 1. Identify Learning Objective
Define what this example teaches:
- What specific concept or technique does this demonstrate?
- Why is this approach useful?
- When should readers apply this pattern?
- How does this fit into the chapter's learning objectives?
**Example:** "Demonstrate JWT authentication middleware in Express.js to show secure API endpoint protection."
### 2. Choose Complexity Level
Select appropriate complexity:
- **Basic**: Single concept, minimal dependencies, <30 lines
- **Intermediate**: Multiple concepts, moderate structure, 30-100 lines
- **Advanced**: Complex interactions, full patterns, 100+ lines
Match complexity to:
- Reader's current skill level
- Chapter position in book
- Concept difficulty
### 3. Write Working Code
Create the code example:
**Code Quality Requirements:**
- [ ] Code executes successfully without errors
- [ ] Follows language-specific style guide (PEP 8, Airbnb JS, Google Java, etc.)
- [ ] Uses descriptive variable and function names
- [ ] Includes inline comments explaining WHY, not WHAT
- [ ] Demonstrates proper error handling
- [ ] Is DRY (Don't Repeat Yourself)
- [ ] Avoids hardcoded values (use constants/config)
- [ ] Includes all necessary imports/dependencies
**Comment Guidelines:**
- Explain design decisions and tradeoffs
- Highlight key concepts being demonstrated
- Point out important details
- Don't explain obvious syntax
### 4. Test Code Thoroughly
Verify the code works:
- Run code on target version (e.g., Python 3.11+, Node 18+)
- Test on target platforms (Windows/Mac/Linux if applicable)
- Verify output matches expectations
- Test edge cases and error conditions
- Document exact test commands used
- Include expected output
**Testing Checklist:**
- [ ] Code runs without modification
- [ ] Dependencies install correctly
- [ ] Output is as documented
- [ ] Error handling works
- [ ] Edge cases covered
### 5. Write Detailed Explanation
Explain the code thoroughly:
- **Overall structure**: How is the code organized?
- **Key concepts**: What techniques are demonstrated?
- **Design decisions**: Why this approach over alternatives?
- **Tradeoffs**: What are the pros and cons?
- **Important details**: What might readers miss?
- **Integration**: How do parts work together?
Connect code to theory:
- Reference chapter concepts
- Explain how code implements theory
- Show practical application of principles
### 6. Document Prerequisites and Setup
Provide complete setup instructions:
- Prior knowledge required
- Software/tools needed (with versions)
- Dependencies to install (exact commands)
- Environment setup (virtual env, Docker, etc.)
- Configuration needed
- Verification steps
**Setup Template:**
```
Prerequisites:
- Python 3.11 or higher
- pip package manager
- Virtual environment (recommended)
Setup:
1. Create virtual environment: python -m venv venv
2. Activate: source venv/bin/activate (Mac/Linux) or venv\Scripts\activate (Windows)
3. Install dependencies: pip install -r requirements.txt
4. Verify: python --version (should show 3.11+)
```
### 7. Add Common Mistakes Section
Document pitfalls:
- What mistakes do beginners commonly make?
- Why are these mistakes problematic?
- How to identify these issues
- Corrected examples
**Example:**
```
❌ Common Mistake: Hardcoding API keys
```
api_key = "sk-1234567890abcdef"
```
✅ Correct Approach: Use environment variables
```
api_key = os.getenv("API_KEY")
```
```
### 8. Create Variations and Extensions
Show how to adapt the example:
- Alternative implementations
- How to extend functionality
- When to use variations
- More advanced patterns building on this
- Real-world applications
### 9. Generate Code Example Document
Use the create-doc.md task with code-example-tmpl.yaml template to create the structured code example document.
### 10. Validate Code Quality
Run checklists:
- code-quality-checklist.md - Verify code follows standards
- code-testing-checklist.md - Ensure thorough testing
- version-compatibility-checklist.md - Confirm version support
## Success Criteria
A completed code example should have:
- [ ] Working code that executes successfully
- [ ] Follows language-specific style guide
- [ ] Inline comments explain WHY, not WHAT
- [ ] Tested on target version(s)
- [ ] Complete setup instructions
- [ ] Detailed explanation connecting code to concepts
- [ ] Prerequisites clearly documented
- [ ] Common mistakes section
- [ ] Variations and extensions
- [ ] Testing approach defined
- [ ] All checklists passed
## Common Pitfalls to Avoid
- **Untested code**: Always run code before documenting
- **Missing dependencies**: List ALL requirements
- **Poor comments**: Explain decisions, not syntax
- **Hardcoded values**: Use constants or configuration
- **Insufficient error handling**: Show proper error management
- **Outdated syntax**: Use current language features
- **Platform assumptions**: Test on target platforms
- **No explanation**: Code alone doesn't teach
## Next Steps
After creating the code example:
1. Add code file to chapter's code repository
2. Create unit tests (if appropriate)
3. Test on all supported platforms
4. Integrate into chapter narrative
5. Cross-reference from related sections

103
expansion-packs/bmad-technical-writing/tasks/create-doc.md Normal file
View File

@ -0,0 +1,103 @@
<!-- Powered by BMAD™ Core -->
# Create Document from Template (YAML Driven)
## ⚠️ CRITICAL EXECUTION NOTICE ⚠️
**THIS IS AN EXECUTABLE WORKFLOW - NOT REFERENCE MATERIAL**
When this task is invoked:
1. **DISABLE ALL EFFICIENCY OPTIMIZATIONS** - This workflow requires full user interaction
2. **MANDATORY STEP-BY-STEP EXECUTION** - Each section must be processed sequentially with user feedback
3. **ELICITATION IS REQUIRED** - When `elicit: true`, you MUST use the 1-9 format and wait for user response
4. **NO SHORTCUTS ALLOWED** - Complete documents cannot be created without following this workflow
**VIOLATION INDICATOR:** If you create a complete document without user interaction, you have violated this workflow.
## Critical: Template Discovery
If a YAML Template has not been provided, list all templates from .bmad-creative-writing/templates or ask the user to provide another.
## CRITICAL: Mandatory Elicitation Format
**When `elicit: true`, this is a HARD STOP requiring user interaction:**
**YOU MUST:**
1. Present section content
2. Provide detailed rationale (explain trade-offs, assumptions, decisions made)
3. **STOP and present numbered options 1-9:**
- **Option 1:** Always "Proceed to next section"
- **Options 2-9:** Select 8 methods from data/elicitation-methods
- End with: "Select 1-9 or just type your question/feedback:"
4. **WAIT FOR USER RESPONSE** - Do not proceed until user selects option or provides feedback
**WORKFLOW VIOLATION:** Creating content for elicit=true sections without user interaction violates this task.
**NEVER ask yes/no questions or use any other format.**
## Processing Flow
1. **Parse YAML template** - Load template metadata and sections
2. **Set preferences** - Show current mode (Interactive), confirm output file
3. **Process each section:**
- Skip if condition unmet
- Check agent permissions (owner/editors) - note if section is restricted to specific agents
- Draft content using section instruction
- Present content + detailed rationale
- **IF elicit: true** → MANDATORY 1-9 options format
- Save to file if possible
4. **Continue until complete**
## Detailed Rationale Requirements
When presenting section content, ALWAYS include rationale that explains:
- Trade-offs and choices made (what was chosen over alternatives and why)
- Key assumptions made during drafting
- Interesting or questionable decisions that need user attention
- Areas that might need validation
## Elicitation Results Flow
After user selects elicitation method (2-9):
1. Execute method from data/elicitation-methods
2. Present results with insights
3. Offer options:
- **1. Apply changes and update section**
- **2. Return to elicitation menu**
- **3. Ask any questions or engage further with this elicitation**
## Agent Permissions
When processing sections with agent permission fields:
- **owner**: Note which agent role initially creates/populates the section
- **editors**: List agent roles allowed to modify the section
- **readonly**: Mark sections that cannot be modified after creation
**For sections with restricted access:**
- Include a note in the generated document indicating the responsible agent
- Example: "_(This section is owned by dev-agent and can only be modified by dev-agent)_"
## YOLO Mode
User can type `#yolo` to toggle to YOLO mode (process all sections at once).
## CRITICAL REMINDERS
**❌ NEVER:**
- Ask yes/no questions for elicitation
- Use any format other than 1-9 numbered options
- Create new elicitation methods
**✅ ALWAYS:**
- Use exact 1-9 format when elicit: true
- Select options 2-9 from data/elicitation-methods only
- Provide detailed rationale explaining decisions
- End with "Select 1-9 or just type your question/feedback:"

249
expansion-packs/bmad-technical-writing/tasks/create-learning-objectives.md Normal file
View File

@ -0,0 +1,249 @@
<!-- Powered by BMAD™ Core -->
# Create Learning Objectives
---
task:
id: create-learning-objectives
name: Create Learning Objectives
description: Define measurable learning objectives for chapter or book section
persona_default: instructional-designer
inputs:
- chapter-or-section
- target-audience
steps:
- Review chapter/section topic and content scope
- Define 3-5 learning objectives using action verbs from Bloom's Taxonomy
- Map objectives to Bloom's levels (Remember, Understand, Apply, Analyze, Evaluate, Create)
- Ensure objectives are measurable and specific
- Align objectives with book's overall learning path
- Define success criteria for each objective
- Identify assessment methods (exercises, projects, quizzes)
- Validate prerequisites are clear
- Run execute-checklist.md with learning-objectives-checklist.md
- Document estimated learning time
output: Adds learning objectives section to chapter outline or book outline
---
## Purpose
This task helps you craft clear, measurable learning objectives that guide both the author (what to teach) and the reader (what they'll achieve). Well-defined objectives improve learning outcomes and book quality.
## Prerequisites
Before starting this task:
- Chapter or section topic identified
- Target audience skill level known
- Access to learning-frameworks.md knowledge base
- Understanding of Bloom's Taxonomy
## Bloom's Taxonomy Reference
Use action verbs appropriate to the learning level:
**Remember** (recall facts):
- Define, List, Name, Identify, Describe, Recognize
**Understand** (explain concepts):
- Explain, Summarize, Interpret, Compare, Classify
**Apply** (use knowledge):
- Implement, Execute, Use, Apply, Demonstrate, Build
**Analyze** (examine components):
- Analyze, Debug, Troubleshoot, Differentiate, Examine
**Evaluate** (make judgments):
- Evaluate, Assess, Critique, Optimize, Justify
**Create** (produce new work):
- Design, Create, Develop, Architect, Construct
## Workflow Steps
### 1. Review Content Scope
Understand what this chapter/section will cover:
- Main topics to be taught
- Depth of coverage
- Prerequisites assumed
- Where this fits in overall book
### 2. Draft Learning Objectives
Create 3-5 objectives following this formula:
**[Action Verb] + [Object] + [Context/Constraint]**
**Good Examples:**
- "Implement JWT authentication in an Express.js REST API"
- "Analyze database query performance using profiling tools"
- "Design a scalable microservices architecture using Docker"
- "Debug React component rendering issues using React DevTools"
**Bad Examples (too vague):**
- "Understand authentication" (no action, not measurable)
- "Learn about databases" (too broad, no specificity)
- "Know React" (not measurable, no context)
### 3. Map to Bloom's Taxonomy
Assign each objective to a Bloom's level:
- **Early chapters**: Focus on Remember, Understand, Apply
- **Middle chapters**: Focus on Apply, Analyze
- **Later chapters**: Focus on Analyze, Evaluate, Create
Ensure progression across book chapters.
### 4. Verify Measurability
Each objective should be testable:
**Ask:** "How will readers prove they've achieved this?"
**Assessment Methods:**
- Build a working project
- Complete coding exercises
- Answer quiz questions
- Debug sample problems
- Create something new
### 5. Define Success Criteria
For each objective, specify what "success" looks like:
**Example:**
- **Objective**: "Implement JWT authentication in Express.js REST API"
- **Success Criteria**:
- User can register and receive JWT token
- Protected routes verify token correctly
- Invalid tokens are rejected with 401 error
- Tokens expire after specified time
### 6. Check Alignment with Book Learning Path
Verify objectives fit the progression:
- Do they build on previous chapters?
- Do they prepare for future chapters?
- Are they appropriate for target audience skill level?
- Do they contribute to book-level objectives?
### 7. Identify Assessment Methods
Determine how readers will practice:
- **Exercises**: Step-by-step guided practice
- **Challenges**: Independent problem-solving
- **Projects**: Comprehensive application
- **Quizzes**: Knowledge checks
- **Debugging tasks**: Fix broken code
### 8. Validate Prerequisites
For each objective, ensure prerequisites are clear:
- What must readers know before starting?
- Which previous chapters must be completed?
- What external knowledge is assumed?
- Are prerequisites explicitly stated?
### 9. Estimate Learning Time
Provide realistic time estimates:
- Time to read/study content
- Time to complete exercises
- Time for practice and experimentation
- Total chapter completion time
### 10. Run Quality Checklist
Execute learning-objectives-checklist.md:
- [ ] Objectives use action verbs (Bloom's taxonomy)
- [ ] Objectives are measurable
- [ ] Objectives align with content
- [ ] Prerequisites clearly stated
- [ ] Difficulty level appropriate
## Success Criteria
Learning objectives are complete when:
- [ ] 3-5 objectives defined per chapter/section
- [ ] All objectives use measurable action verbs
- [ ] Mapped to Bloom's Taxonomy levels
- [ ] Success criteria defined for each
- [ ] Assessment methods identified
- [ ] Prerequisites validated
- [ ] Aligned with book learning path
- [ ] Time estimates provided
- [ ] learning-objectives-checklist.md passed
## Common Pitfalls to Avoid
- **Too vague**: "Understand databases" → "Design normalized relational database schemas"
- **Not measurable**: "Know about async" → "Implement asynchronous code using Promises and async/await"
- **Too many objectives**: Stick to 3-5 key objectives per chapter
- **Wrong Bloom's level**: Don't ask beginners to "Evaluate" or "Create" in early chapters
- **No assessment**: Always define how objectives will be verified
- **Misalignment**: Objectives don't match actual chapter content
## Examples by Bloom's Level
**Remember (Early chapters):**
- "List the main components of the React ecosystem"
- "Identify common SQL query types (SELECT, INSERT, UPDATE, DELETE)"
**Understand (Early-mid chapters):**
- "Explain how async/await improves code readability compared to callbacks"
- "Describe the request-response cycle in Express.js applications"
**Apply (Mid chapters):**
- "Implement user authentication using Passport.js and sessions"
- "Build a RESTful API with CRUD operations for a blog platform"
**Analyze (Mid-late chapters):**
- "Debug memory leaks in Node.js applications using Chrome DevTools"
- "Analyze API performance bottlenecks using profiling tools"
**Evaluate (Late chapters):**
- "Evaluate trade-offs between SQL and NoSQL databases for specific use cases"
- "Assess security vulnerabilities in web applications using OWASP guidelines"
**Create (Late chapters):**
- "Design a scalable microservices architecture for an e-commerce platform"
- "Develop a CI/CD pipeline for automated testing and deployment"
## Next Steps
After creating learning objectives:
1. Share with technical reviewers for feedback
2. Use objectives to guide chapter content creation
3. Design exercises that directly assess objectives
4. Create summary section that reviews objective completion
5. Test with beta readers to verify achievability

199
expansion-packs/bmad-technical-writing/tasks/design-book-outline.md Normal file
View File

@ -0,0 +1,199 @@
<!-- Powered by BMAD™ Core -->
# Design Book Outline
---
task:
id: design-book-outline
name: Design Book Outline
description: Create complete technical book structure with learning path and chapter breakdown
persona_default: instructional-designer
inputs:
- book-topic
- target-audience
- publisher-target (PacktPub, O'Reilly, Manning, Self-publish)
steps:
- Elicit book concept, target audience, and technical scope
- Identify learning objectives for entire book (what readers will accomplish)
- Review publisher-specific structure requirements from book-structures.md
- Break into logical parts/sections based on learning progression
- Design chapter sequence ensuring proper scaffolding (simple to complex)
- For each chapter, define learning objectives and main topics
- Map prerequisites and dependencies between chapters
- Apply Bloom's Taxonomy to ensure progression (Remember→Understand→Apply→Analyze→Evaluate→Create)
- Plan code repository structure and testing approach
- Estimate page counts and timeline
- Use template book-outline-tmpl.yaml with create-doc.md task
- Run execute-checklist.md with learning-objectives-checklist.md
- Run execute-checklist.md with prerequisite-clarity-checklist.md
output: docs/book-outline.md
---
## Purpose
This task guides you through creating a comprehensive book outline that balances publisher requirements, learning pedagogy, and technical accuracy. The result is a complete roadmap for the entire book.
## Prerequisites
Before starting this task:
- Have a clear book topic and target technology
- Know your target reader's skill level
- Understand which publisher you're targeting (or self-publishing)
- Access to book-structures.md and learning-frameworks.md knowledge bases
## Workflow Steps
### 1. Elicit Book Concept and Audience
Ask the user about:
- Book topic and core technology/framework
- Target reader's skill level (beginner, intermediate, advanced)
- Prerequisites readers should have
- What readers will accomplish after reading
- Estimated book length (200-400 pages typical)
- Publisher target (PacktPub, O'Reilly, Manning, self-publish)
### 2. Review Publisher Requirements
Consult book-structures.md for publisher-specific guidelines:
- **PacktPub**: Hands-on, project-based, practical tutorials
- **O'Reilly**: Learning path with exercises and examples
- **Manning**: Deep tutorial style with progressive complexity
- **Self-publish**: Flexible structure, but follow best practices
### 3. Define Book-Level Learning Objectives
Identify 5-10 major learning objectives for the entire book using action verbs:
- What will readers be able to CREATE after reading?
- What technologies will they IMPLEMENT?
- What concepts will they ANALYZE and EVALUATE?
Ensure objectives are:
- Measurable and specific
- Appropriate for target skill level
- Achievable within book scope
### 4. Design Part/Section Structure
Break the book into logical parts (typically 3-5 parts):
**Example Structure:**
- Part I: Foundations (Chapters 1-4)
- Part II: Core Concepts (Chapters 5-8)
- Part III: Advanced Topics (Chapters 9-12)
- Part IV: Real-World Applications (Chapters 13-15)
Each part should have:
- Clear learning arc
- Coherent theme
- Progressive difficulty
### 5. Create Chapter Sequence
For each chapter, define:
- Chapter number and title
- 3-5 learning objectives (using Bloom's taxonomy action verbs)
- Main topics covered
- Tutorials and exercises planned
- Code examples needed
- Estimated page count
- Prerequisites (which chapters must come before)
- Difficulty level
**Scaffolding Guidelines:**
- Start simple, add complexity gradually
- Each chapter builds on previous knowledge
- Introduce concepts before using them
- Provide practice before advancing
### 6. Map Dependencies
Create a dependency map:
- Which chapters must be completed before others?
- What external knowledge is assumed?
- Where are the major skill milestones?
- Are there any optional chapters?
### 7. Apply Bloom's Taxonomy
Ensure learning progression across the book:
- **Early chapters**: Remember, Understand (definitions, concepts)
- **Middle chapters**: Apply, Analyze (hands-on practice, debugging)
- **Later chapters**: Evaluate, Create (optimization, design decisions)
### 8. Plan Code Repository
Design companion code structure:
- Chapter folder organization
- Testing strategy (unit tests, integration tests)
- Version compatibility targets
- CI/CD pipeline for validation
### 9. Generate Book Outline
Use the create-doc.md task with book-outline-tmpl.yaml template to create the structured outline document.
### 10. Validate Outline
Run checklists:
- learning-objectives-checklist.md - Verify all objectives are measurable
- prerequisite-clarity-checklist.md - Ensure prerequisites are explicit
### 11. Review and Refine
Ask the user:
- Does the chapter progression feel natural?
- Are there any gaps in coverage?
- Is the scope appropriate for the target page count?
- Does this match publisher expectations?
## Success Criteria
A completed book outline should have:
- [ ] Clear target audience and prerequisites defined
- [ ] Book-level learning objectives (5-10 measurable outcomes)
- [ ] Part structure with 3-5 logical groupings
- [ ] Complete chapter list (typically 12-20 chapters)
- [ ] Each chapter has 3-5 learning objectives
- [ ] Dependencies and prerequisites mapped
- [ ] Scaffolding ensures proper progression
- [ ] Code repository structure planned
- [ ] Estimated page counts and timeline
- [ ] Publisher requirements incorporated
- [ ] All checklists passed
## Common Pitfalls to Avoid
- **Too much coverage**: Better to go deep on fewer topics
- **Poor scaffolding**: Don't use concepts before explaining them
- **Missing prerequisites**: Be explicit about what readers need
- **Inconsistent difficulty**: Avoid sudden jumps in complexity
- **No practice**: Include exercises and tutorials throughout
- **Ignoring publisher style**: Each publisher has specific expectations
## Next Steps
After completing the book outline:
1. Review with technical experts or potential readers
2. Create detailed chapter outlines (create-chapter-outline.md)
3. Begin drafting first chapter
4. Set up code repository structure

287
expansion-packs/bmad-technical-writing/tasks/test-code-examples.md Normal file
View File

@ -0,0 +1,287 @@
<!-- Powered by BMAD™ Core -->
# Test Code Examples
---
task:
id: test-code-examples
name: Test Code Examples
description: Run automated tests on all code examples in chapter or book
persona_default: code-curator
inputs:
- chapter-number (or "all" for entire book)
- target-versions
steps:
- Identify all code examples in specified scope
- Set up testing environment with target versions
- For each code example, run the code
- Verify output matches documentation
- Test on specified platforms (Windows/Mac/Linux if applicable)
- Check edge cases and error handling
- Document any version-specific behaviors
- Update code-testing-checklist.md as you test
- Fix any failing examples
- Document testing results
output: docs/testing/code-test-results.md
---
## Purpose
This task ensures all code examples work correctly across specified versions and platforms. Technical books lose credibility if code doesn't work, so thorough testing is critical.
## Prerequisites
Before starting this task:
- Code examples have been created
- Target versions identified (e.g., Python 3.11-3.12, Node 18-20)
- Access to testing environments for target versions
- code-testing-checklist.md available
## Workflow Steps
### 1. Identify Code Examples
Collect all code examples in scope:
**For Single Chapter:**
- List all code files in chapter's code folder
- Identify inline code snippets that should be tested
- Note any setup dependencies between examples
**For Entire Book:**
- Scan all chapter folders
- Create comprehensive list of examples
- Group by language/framework
- Identify shared dependencies
### 2. Set Up Testing Environment
Prepare testing infrastructure:
**Environment Requirements:**
- [ ] Target language versions installed (e.g., Python 3.11, 3.12, 3.13)
- [ ] Package managers available (pip, npm, maven, etc.)
- [ ] Virtual environments or containers ready
- [ ] Required platforms (Windows/Mac/Linux) if multi-platform
- [ ] CI/CD pipeline configured (optional but recommended)
**Environment Setup Example (Python):**
```bash
# Create test environment for Python 3.11
pyenv install 3.11.5
pyenv virtualenv 3.11.5 book-test-3.11
# Create test environment for Python 3.12
pyenv install 3.12.0
pyenv virtualenv 3.12.0 book-test-3.12
```
### 3. Test Each Example
For every code example:
**Step 1: Fresh Environment**
- Start with clean environment
- Install only documented dependencies
- Use exact versions from requirements
**Step 2: Run Code**
- Execute code exactly as documented
- Capture output
- Note execution time
- Watch for warnings
**Step 3: Verify Output**
- Compare output to documentation
- Check for expected results
- Verify error messages (if testing error cases)
- Ensure no unexpected warnings
**Step 4: Test Edge Cases**
- Empty inputs
- Boundary values
- Invalid inputs
- Error conditions
- Large datasets (if applicable)
**Step 5: Document Results**
- ✅ PASS: Works as documented
- ⚠️ WARNING: Works but with warnings
- ❌ FAIL: Does not work as documented
- 📝 NOTE: Version-specific behavior
### 4. Platform Testing
If book targets multiple platforms:
**Test on Each Platform:**
- Windows (PowerShell and CMD if relevant)
- macOS (latest 2 versions)
- Linux (Ubuntu/Debian typical)
**Platform-Specific Issues:**
- Path separators (/ vs \)
- Line endings (LF vs CRLF)
- Case sensitivity
- Default encodings
- Command syntax
### 5. Version Compatibility Testing
Test across supported versions:
**For Each Target Version:**
- Run full test suite
- Document version-specific behaviors
- Note deprecated features
- Identify breaking changes
- Update version compatibility matrix
**Version Matrix Example:**
| Example | Python 3.11 | Python 3.12 | Python 3.13 |
| ---------------- | ----------- | ----------- | ----------- |
| basic-server.py | ✅ PASS | ✅ PASS | ✅ PASS |
| async-handler.py | ✅ PASS | ✅ PASS | ⚠️ WARNING |
| type-hints.py | ✅ PASS | ✅ PASS | ✅ PASS |
### 6. Handle Test Failures
When code fails:
**Step 1: Diagnose**
- What is the error message?
- Is it environment-related or code-related?
- Does it fail on all versions/platforms?
- Is documentation incorrect?
**Step 2: Fix**
- Update code if bug found
- Update documentation if instructions wrong
- Add troubleshooting section if common issue
- Update requirements if dependency changed
**Step 3: Retest**
- Verify fix works
- Test on all affected versions/platforms
- Update test results
### 7. Update Code-Testing Checklist
As you test, mark items on code-testing-checklist.md:
- [ ] Every example tested
- [ ] Runs on specified versions
- [ ] Output matches documentation
- [ ] Edge cases considered
- [ ] Error cases demonstrated
- [ ] Testing instructions provided
- [ ] Platform-specific issues documented
### 8. Document Testing Results
Create comprehensive test report:
**Report Structure:**
1. **Summary**: Total examples, pass/fail/warning counts
2. **Environment**: Versions tested, platforms, date
3. **Results**: Detailed results for each example
4. **Issues Found**: List of problems and fixes
5. **Recommendations**: Suggested improvements
6. **Version Notes**: Version-specific behaviors
### 9. Fix Failing Examples
For each failure:
1. Document the issue
2. Fix code or documentation
3. Retest to confirm fix
4. Update code repository
5. Note fix in change log
### 10. Continuous Testing
Set up automated testing (optional):
- Create CI/CD pipeline (GitHub Actions, GitLab CI, etc.)
- Run tests on every commit
- Test across version matrix
- Generate test reports automatically
## Success Criteria
Testing is complete when:
- [ ] All code examples identified
- [ ] Testing environment set up for all target versions
- [ ] Every example tested successfully
- [ ] Output verified against documentation
- [ ] Edge cases tested
- [ ] Platform-specific testing done (if applicable)
- [ ] Version compatibility matrix created
- [ ] All failures fixed and retested
- [ ] code-testing-checklist.md completed
- [ ] Test results documented
## Common Pitfalls to Avoid
- **Testing in wrong environment**: Use clean environments
- **Skipping versions**: Test ALL supported versions
- **Ignoring warnings**: Warnings can become errors
- **No edge case testing**: Test boundary conditions
- **Missing dependencies**: Document ALL requirements
- **Platform assumptions**: Test on all target platforms
- **Stale documentation**: Update docs when code changes
- **No automation**: Manual testing is error-prone and slow
## Testing Tools by Language
**Python:**
- pytest (unit testing)
- tox (multi-version testing)
- coverage.py (code coverage)
**JavaScript/Node:**
- Jest (testing framework)
- nvm (version management)
- npm test (standard test runner)
**Java:**
- JUnit (testing framework)
- Maven/Gradle (build and test)
- jenv (version management)
## Next Steps
After testing is complete:
1. Fix any failing examples
2. Update documentation with any clarifications
3. Add troubleshooting sections where needed
4. Set up CI/CD for continuous testing
5. Retest before each book edition
6. Test again when new language versions released

87
expansion-packs/bmad-technical-writing/templates/book-outline-tmpl.yaml Normal file
View File

@ -0,0 +1,87 @@
# <!-- Powered by BMAD™ Core -->
---
template:
id: book-outline
name: Complete Book Outline
version: 1.0
description: Full book structure with learning path and chapter breakdown
output:
format: markdown
filename: "{{book_title}}-outline.md"
workflow:
elicitation: true
allow_skip: false
sections:
- id: metadata
title: Book Metadata
instruction: |
Core information:
- Title and subtitle
- Target audience (skill level, role)
- Prerequisites (what readers need to know)
- Learning outcomes (what readers will accomplish)
- Estimated length (page count)
- Publisher target (PacktPub, O'Reilly, Manning, Self-publish)
- Technology stack and versions
elicit: true
- id: front_matter
title: Front Matter Plan
instruction: |
Plan front matter sections:
- Preface/Introduction topics to cover
- About the author section
- How to use this book
- Conventions used (code formatting, callouts)
- Prerequisites and setup instructions
- Companion code repository location
- id: part_structure
title: Part/Section Organization
instruction: |
Organize book into parts (if applicable):
- Part 1: [Title] - Chapters X-Y (focus area)
- Part 2: [Title] - Chapters X-Y (focus area)
- Part 3: [Title] - Chapters X-Y (focus area)
For each part, describe the learning arc and why chapters are grouped this way.
- id: chapter_outlines
title: Chapter-by-Chapter Outline
instruction: |
For each chapter, define:
- Chapter number and title
- Learning objectives (3-5 measurable outcomes using action verbs)
- Topics covered (main concepts and techniques)
- Tutorials/exercises planned (hands-on activities)
- Code examples needed (list major examples)
- Estimated page count
- Prerequisites (which previous chapters must be completed)
- Difficulty level (beginner, intermediate, advanced)
elicit: true
- id: learning_path
title: Learning Path Progression
instruction: |
Document the overall learning progression:
- How does difficulty increase across chapters?
- What is the scaffolding strategy?
- How do chapters build on each other?
- Where are the major skill milestones?
- Map to Bloom's Taxonomy levels (Remember→Understand→Apply→Analyze→Evaluate→Create)
- id: back_matter
title: Back Matter Plan
instruction: |
Plan appendices and references:
- Appendix topics (reference material, additional tutorials)
- Glossary scope (key terms to define)
- Index strategy (important topics to index)
- Additional resources (books, websites, tools)
- Answer key (if exercises have solutions)
- id: code_repo
title: Code Repository Plan
instruction: |
Companion code structure:
- Repository organization (folder structure)
- Chapter folders naming convention
- Testing strategy (unit tests, integration tests)
- Version/platform support (Python 3.11+, Node 18+, etc.)
- CI/CD pipeline for code validation
- README structure for each chapter

95
expansion-packs/bmad-technical-writing/templates/chapter-outline-tmpl.yaml Normal file
View File

@ -0,0 +1,95 @@
# <!-- Powered by BMAD™ Core -->
---
template:
id: chapter-outline
name: Chapter Outline
version: 1.0
description: Detailed single chapter structure with learning objectives and content breakdown
output:
format: markdown
filename: "chapter-{{chapter_number}}-outline.md"
workflow:
elicitation: true
allow_skip: false
sections:
- id: metadata
title: Chapter Metadata
instruction: |
Basic information:
- Chapter number and title
- Estimated page count
- Time to complete (for reader, e.g., "2-3 hours")
- Difficulty level (beginner, intermediate, advanced)
- Part/section this belongs to (if applicable)
elicit: true
- id: objectives
title: Learning Objectives
instruction: |
What readers will learn (3-5 objectives):
- Use action verbs from Bloom's Taxonomy (create, analyze, implement, evaluate, design)
- Be specific and measurable
- Align with book-level learning path
- Examples:
* "Implement JWT authentication in a REST API"
* "Analyze performance bottlenecks using profiling tools"
* "Create reusable React components with TypeScript"
elicit: true
- id: prerequisites
title: Prerequisites
instruction: |
What readers need before starting:
- Previous chapters that must be completed
- External knowledge/skills assumed
- Software/tools required (with version numbers)
- Setup or configuration needed
- Estimated time for setup
- id: introduction
title: Introduction Section
instruction: |
Chapter opening (1-2 pages):
- Hook/motivating example (real-world problem this solves)
- Overview of topics to be covered
- Real-world relevance and use cases
- Why this matters in the broader context
elicit: true
- id: sections
title: Main Content Sections
instruction: |
For each major section of the chapter:
- Section title and subtitle
- Concept explanation (theory/background)
- Tutorial/walkthrough (hands-on implementation)
- Code examples needed (list filenames and purpose)
- Diagrams/screenshots needed (describe visual aids)
- Common mistakes to highlight
- Troubleshooting tips
List sections in order, with estimated page count for each.
elicit: true
- id: exercises
title: Exercises & Challenges
instruction: |
Practice opportunities:
- Guided practice exercises (3-4 exercises that walk through steps)
- Challenge problems (1-2 harder problems requiring independent work)
- Difficulty progression (easy to challenging)
- Solutions provided? (yes/no, or "hints only")
- Estimated time for each exercise
- id: summary
title: Summary & Next Steps
instruction: |
Chapter conclusion (1 page):
- Key concepts recap (bullet list)
- What was accomplished (skill checklist)
- Preview of next chapter (how it builds on this)
- Additional resources (optional reading, tools, documentation)
- id: code_files
title: Code Files List
instruction: |
Code examples for this chapter:
- Filename (e.g., "auth-middleware.js")
- Purpose (brief description)
- Language and version (e.g., "Python 3.11+")
- Testing requirements (unit tests, integration tests)
- Dependencies (external packages needed)

114
expansion-packs/bmad-technical-writing/templates/code-example-tmpl.yaml Normal file
View File

@ -0,0 +1,114 @@
# <!-- Powered by BMAD™ Core -->
---
template:
id: code-example
name: Code Example Template
version: 1.0
description: Documented code example with explanation and testing approach
output:
format: markdown
filename: "{{example_name}}-example.md"
workflow:
elicitation: true
allow_skip: false
sections:
- id: metadata
title: Example Metadata
instruction: |
Basic information:
- Example name/title
- Programming language (e.g., Python, JavaScript, Java)
- Language version (e.g., Python 3.11+, Node 18+)
- Purpose (what this example demonstrates)
- Complexity level (basic, intermediate, advanced)
- Related chapter/section
elicit: true
- id: learning_objective
title: Learning Objective
instruction: |
What readers will learn from this example:
- Specific concept or technique demonstrated
- Why this approach is useful
- When to apply this pattern
- How it fits into the larger topic
- id: prerequisites
title: Prerequisites
instruction: |
What readers need before using this example:
- Prior knowledge required
- Software/tools needed (with installation links)
- Dependencies to install (with version requirements)
- Environment setup (virtual env, containers, etc.)
- id: setup
title: Setup Instructions
instruction: |
Step-by-step setup:
1. How to set up the environment
2. Dependencies to install (exact commands)
3. Configuration needed
4. File structure/organization
5. Verification steps (how to confirm setup worked)
elicit: true
- id: code
title: Code Implementation
instruction: |
The complete working code with inline comments:
- Include all necessary imports
- Add inline comments explaining WHY, not WHAT
- Highlight key concepts with comments
- Use descriptive variable/function names
- Follow language-specific style guide
- Ensure code is DRY and maintainable
- Include error handling
Format as code block with language identifier.
elicit: true
- id: explanation
title: Code Explanation
instruction: |
Detailed walkthrough of the code:
- Explain the overall structure/flow
- Highlight key concepts being demonstrated
- Explain design decisions and tradeoffs
- Connect code to theoretical concepts
- Point out important details readers might miss
- Explain how different parts work together
elicit: true
- id: common_mistakes
title: Common Mistakes to Avoid
instruction: |
Pitfalls and antipatterns:
- What mistakes do beginners commonly make?
- Why are these mistakes problematic?
- How to identify these issues
- Corrected examples
- id: variations
title: Variations & Extensions
instruction: |
How to adapt this example:
- Alternative implementations
- How to extend functionality
- When to use variations
- More advanced patterns building on this
- Real-world applications
- id: testing
title: Testing Approach
instruction: |
How to verify this code works:
- Test commands to run
- Expected output
- How to verify correctness
- Unit tests (if applicable)
- Edge cases to test
- Platform-specific testing notes (Windows/Mac/Linux)
elicit: true
- id: troubleshooting
title: Troubleshooting
instruction: |
Common issues and solutions:
- Error messages readers might encounter
- Debugging steps
- Platform-specific issues
- Version compatibility problems
- Where to get help